Retell AI Register Phone Call API

openapi: 3.2.0
info:
  title: Retell SDK Add Community Voice Register Phone Call API
  version: 3.0.0
  contact:
    name: Retell Support
    url: https://www.retellai.com/
    email: support@retellai.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
  description: The production server.
security:
- api_key: []
tags:
- name: Register Phone Call
paths:
  /v2/register-phone-call:
    post:
      description: Register a new phone call for custom telephony
      operationId: registerPhoneCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              properties:
                agent_id:
                  type: string
                  minLength: 1
                  example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
                  description: The agent to use for the call.
                agent_version:
                  $ref: '#/components/schemas/AgentVersionReference'
                  description: The version of the agent to use for the call.
                agent_override:
                  $ref: '#/components/schemas/AgentOverrideRequest'
                  description: For this particular call, override agent configuration with these settings. This allows you to customize agent behavior for individual calls without modifying the base agent.
                from_number:
                  type: string
                  minLength: 1
                  example: '+14157774444'
                  description: The number you own in E.164 format. Stored for tracking purpose.
                to_number:
                  type: string
                  minLength: 1
                  example: '+12137774445'
                  description: The number you want to call, in E.164 format. Stored for tracking purpose.
                direction:
                  type: string
                  enum:
                  - inbound
                  - outbound
                  example: inbound
                  description: Direction of the phone call. Stored for tracking purpose.
                metadata:
                  type: object
                  description: An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object.
                retell_llm_dynamic_variables:
                  type: object
                  additionalProperties: {}
                  example:
                    customer_name: John Doe
                  description: Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.
      responses:
        '201':
          description: Successfully registered a phone call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2PhoneCallResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Register Phone Call
components:
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: API key is missing or invalid.
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Account rate limited, please throttle your requests.
    UnprocessableContent:
      description: Unprocessable Content
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Cannot find requested asset under given api key.
    PaymentRequired:
      description: Payment Required
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Trial has ended, please add payment method.
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Invalid request format, please check API reference.
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: An unexpected server error occurred.
  schemas:
    AnalysisData:
      oneOf:
      - $ref: '#/components/schemas/StringAnalysisData'
      - $ref: '#/components/schemas/EnumAnalysisData'
      - $ref: '#/components/schemas/BooleanAnalysisData'
      - $ref: '#/components/schemas/NumberAnalysisData'
    IvrAction:
      oneOf:
      - $ref: '#/components/schemas/IvrActionHangup'
    VoicemailActionBridgeTransfer:
      type: object
      properties:
        type:
          type: string
          enum:
          - bridge_transfer
          example: bridge_transfer
      required:
      - type
    ToolCallInvocationUtterance:
      type: object
      required:
      - role
      - tool_call_id
      - name
      - arguments
      properties:
        role:
          type: string
          enum:
          - tool_call_invocation
          description: This is a tool call invocation.
        tool_call_id:
          type: string
          description: Tool call id, globally unique.
        name:
          type: string
          description: Name of the function in this tool call.
        arguments:
          type: string
          description: Arguments for this tool call, it's a stringified JSON object.
        thought_signature:
          type: string
          description: Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
    EnumAnalysisData:
      type: object
      required:
      - type
      - name
      - description
      - choices
      properties:
        type:
          type: string
          enum:
          - enum
          description: Type of the variable to extract.
          example: enum
        name:
          type: string
          description: Name of the variable.
          example: product_rating
          minLength: 1
        description:
          type: string
          description: Description of the variable.
          example: Rating of the product.
        choices:
          type: array
          items:
            type: string
          description: The possible values of the variable, must be non empty array.
          example:
          - good
        required:
          type: boolean
          description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
        conditional_prompt:
          type: string
          description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
    ResponseEngineRetellLm:
      type: object
      required:
      - type
      - llm_id
      properties:
        type:
          type: string
          enum:
          - retell-llm
          description: type of the Response Engine.
        llm_id:
          type: string
          description: id of the Retell LLM Response Engine.
        version:
          type:
          - number
          - 'null'
          example: 0
          description: Version of the Retell LLM Response Engine.
    Utterance:
      type: object
      required:
      - role
      - content
      - words
      properties:
        role:
          type: string
          enum:
          - agent
          - user
          - transfer_target
          description: Documents whether this utterance is spoken by agent or user.
          example: agent
        content:
          type: string
          description: Transcript of the utterances.
          example: hi how are you doing?
        words:
          type: array
          example:
          - word: hi
            start: 0.7
            end: 1.3
          description: Array of words in the utterance with the word timestamp. Useful for understanding what word was spoken at what time. Note that the word timestamp is not guaranteed to be accurate, it's more like an approximation.
          items:
            type: object
            properties:
              word:
                type: string
                description: Word transcript (with punctuation if applicable).
              start:
                type: number
                description: Start time of the word in the call in second. This is relative audio time, not wall time.
              end:
                type: number
                description: End time of the word in the call in second. This is relative audio time, not wall time.
    NumberAnalysisData:
      type: object
      required:
      - type
      - name
      - description
      properties:
        type:
          type: string
          enum:
          - number
          description: Type of the variable to extract.
          example: number
        name:
          type: string
          description: Name of the variable.
          example: order_count
          minLength: 1
        description:
          type: string
          description: Description of the variable.
          example: How many the customer intend to order.
        required:
          type: boolean
          description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
        conditional_prompt:
          type: string
          description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
    VoicemailActionHangup:
      type: object
      properties:
        type:
          type: string
          enum:
          - hangup
          example: hangup
      required:
      - type
    V2PhoneCallResponse:
      allOf:
      - type: object
        required:
        - call_type
        - from_number
        - to_number
        - direction
        properties:
          call_type:
            type: string
            enum:
            - phone_call
            example: phone_call
            description: Type of the call. Used to distinguish between web call and phone call.
          from_number:
            type: string
            example: '+12137771234'
            description: The caller number.
          to_number:
            type: string
            example: '+12137771235'
            description: The callee number.
          direction:
            type: string
            enum:
            - inbound
            - outbound
            example: inbound
            description: Direction of the phone call.
          telephony_identifier:
            type: object
            description: Telephony identifier of the call, populated when available. Tracking purposes only.
            properties:
              twilio_call_sid:
                type: string
                example: CA5d0d0d8047bf685c3f0ff980fe62c123
                description: Twilio call sid.
      - $ref: '#/components/schemas/V2CallBase'
    DisconnectionReason:
      type: string
      enum:
      - user_hangup
      - agent_hangup
      - call_transfer
      - voicemail_reached
      - ivr_reached
      - inactivity
      - max_duration_reached
      - concurrency_limit_reached
      - no_valid_payment
      - scam_detected
      - dial_busy
      - dial_failed
      - dial_no_answer
      - invalid_destination
      - telephony_provider_permission_denied
      - telephony_provider_unavailable
      - sip_routing_error
      - marked_as_spam
      - user_declined
      - error_llm_websocket_open
      - error_llm_websocket_lost_connection
      - error_llm_websocket_runtime
      - error_llm_websocket_corrupt_payload
      - error_no_audio_received
      - error_asr
      - error_retell
      - error_unknown
      - error_user_not_joined
      - registered_call_timeout
      - transfer_bridged
      - transfer_cancelled
      - manual_stopped
    CallAnalysis:
      type: object
      properties:
        call_summary:
          type: string
          example: The agent called the user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.
          description: A high level summary of the call.
        in_voicemail:
          type: boolean
          example: false
          description: Whether the call is entered voicemail.
        user_sentiment:
          type: string
          enum:
          - Negative
          - Positive
          - Neutral
          - Unknown
          example: Positive
          description: Sentiment of the user in the call.
        call_successful:
          type: boolean
          example: true
          description: Whether the agent seems to have a successful call with the user, where the agent finishes the task, and the call was complete without being cutoff.
        custom_analysis_data:
          type: object
          description: Custom analysis data that was extracted based on the schema defined in agent post call analysis data. Can be empty if nothing is specified.
    PostCallAnalysisData:
      oneOf:
      - $ref: '#/components/schemas/AnalysisData'
      - $ref: '#/components/schemas/CallPresetAnalysisData'
      description: Post-call analysis item (custom data or voice preset). Use for voice agent post_call_analysis_data; validates only call presets (call_summary, call_successful, user_sentiment).
    ResponseEngineCustomLm:
      type: object
      required:
      - type
      - llm_websocket_url
      properties:
        type:
          type: string
          enum:
          - custom-llm
          description: type of the Response Engine.
        llm_websocket_url:
          type: string
          description: LLM websocket url of the custom LLM.
    StringAnalysisData:
      type: object
      required:
      - type
      - name
      - description
      properties:
        type:
          type: string
          enum:
          - string
          description: Type of the variable to extract.
          example: string
        name:
          type: string
          description: Name of the variable.
          example: customer_name
          minLength: 1
        description:
          type: string
          description: Description of the variable.
          example: The name of the customer.
        examples:
          type: array
          items:
            type: string
          description: Examples of the variable value to teach model the style and syntax.
          example:
          - John Doe
          - Jane Smith
        required:
          type: boolean
          description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
        conditional_prompt:
          type: string
          description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
    ModelChoice:
      oneOf:
      - $ref: '#/components/schemas/ModelChoiceCascading'
    BooleanAnalysisData:
      type: object
      required:
      - type
      - name
      - description
      properties:
        type:
          type: string
          enum:
          - boolean
          description: Type of the variable to extract.
          example: boolean
        name:
          type: string
          description: Name of the variable.
          example: is_converted
          minLength: 1
        description:
          type: string
          description: Description of the variable.
          example: Whether the customer converted.
        required:
          type: boolean
          description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
        conditional_prompt:
          type: string
          description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
    LanguageLegacy:
      oneOf:
      - $ref: '#/components/schemas/Language'
      - type: string
        enum:
        - multi
      example: en-US
      description: Legacy single-string language format. Accepts any concrete locale from `Language`, plus the special scalar value `multi` for multilingual support. If unset, will use default value `en-US`.
    ConversationFlowOverride:
      type: object
      description: Override properties for conversation flow configuration in agent override requests.
      properties:
        model_choice:
          $ref: '#/components/schemas/ModelChoice'
          description: The model choice for the conversation flow.
        model_temperature:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
          example: 0.7
          description: Controls the randomness of the model's responses. Lower values make responses more deterministic.
        tool_call_strict_mode:
          type:
          - boolean
          - 'null'
          example: true
          description: Whether to use strict mode for tool calls. Only applicable when using certain supported models.
        knowledge_base_ids:
          type:
          - array
          - 'null'
          items:
            type: string
          example:
          - kb_001
          - kb_002
          description: Knowledge base IDs for RAG (Retrieval-Augmented Generation).
        kb_config:
          type: object
          $ref: '#/components/schemas/KBConfig'
          description: Knowledge base configuration for RAG retrieval.
        start_speaker:
          type: string
          enum:
          - user
          - agent
          example: agent
          description: Who starts the conversation - user or agent.
        begin_after_user_silence_ms:
          type:
          - integer
          - 'null'
          example: 2000
          description: If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak.
    DTMFUtterance:
      type: object
      required:
      - role
      - digit
      properties:
        role:
          type: string
          enum:
          - dtmf
          description: Digit pressed by the user from their phone keypad.
        digit:
          type: string
          description: The digit pressed by the user. Will be a single digit string like "1", "2", "3", "*", "#" etc.
          example: '1'
    AgentRequest:
      type: object
      properties:
        response_engine:
          $ref: '#/components/schemas/ResponseEngine'
          description: The Response Engine to attach to the agent. It is used to generate responses for the agent. You need to create a Response Engine first before attaching it to an agent.
          example:
            type: retell-llm
            llm_id: llm_234sdertfsdsfsdf
            version: 0
        agent_name:
          type:
          - string
          - 'null'
          example: Jarvis
          description: The name of the agent. Only used for your own reference.
        version_description:
          type:
          - string
          - 'null'
          example: Customer support agent for handling product inquiries
          description: Optional description of the agent version. Used for your own reference and documentation.
        voice_id:
          type: string
          example: retell-Cimo
          description: Unique voice id used for the agent. Find list of available voices and their preview in Dashboard.
        voice_model:
          type:
          - string
          - 'null'
          enum:
          - eleven_turbo_v2
          - eleven_flash_v2
          - eleven_turbo_v2_5
          - eleven_flash_v2_5
          - eleven_multilingual_v2
          - eleven_v3
          - sonic-3
          - sonic-3-latest
          - tts-1
          - gpt-4o-mini-tts
          - speech-02-turbo
          - speech-2.8-turbo
          - s1
          - s2-pro
          - null
          description: Select the voice model used for the selected voice. Each provider has a set of available voice models. Set to null to remove voice model selection, and default ones will apply. Check out dashboard for more details of each voice model.
        fallback_voice_ids:
          type:
          - array
          - 'null'
          items:
            type: string
          example:
          - cartesia-Cimo
          - minimax-Cimo
          description: When TTS provider for the selected voice is experiencing outages, we would use fallback voices listed here for the agent. Voice id and the fallback voice ids must be from different TTS providers. The system would go through the list in order, if the first one in the list is also having outage, it would use the next one. Set to null to remove voice fallback for the agent.
        voice_temperature:
          type: number
          example: 1
          description: Controls how stable the voice is. Value ranging from [0,2]. Lower value means more stable, and higher value means more variant speech generation. Check the dashboard to see what provider supports this feature. If unset, default value 1 will apply.
        voice_speed:
          type: number
          minimum: 0.5
          maximum: 2
          example: 1
          description: Controls speed of voice. Value ranging from [0.5,2]. Lower value means slower speech, while higher value means faster speech rate. If unset, default value 1 will apply.
        enable_dynamic_voice_speed:
          type: boolean
          example: true
          description: If set to true, will enable dynamic voice speed adjustment based on the user's speech rate and conversation context. If unset, default value false will apply.
        enable_dynamic_responsiveness:
          type: boolean
          example: true
          description: If set to true, the agent will dynamically adjust how quickly it responds based on the user's speech rate and past turn-taking behavior in the call. If unset, default value false will apply.
        volume:
          type: number
          example: 1
          description: If set, will control the volume of the agent. Value ranging from [0,2]. Lower value means quieter agent speech, while higher value means louder agent speech. If unset, default value 1 will apply.
        voice_emotion:
          type:
          - string
          - 'null'
          enum:
          - calm
          - sympathetic
          - happy
          - sad
          - angry
          - fearful
          - surprised
          - null
          example: calm
          description: 'Controls the emotional tone of the agent''s voice. Currently supported for Cartesia and Minimax TTS providers. If unset, no emotion will be used.

            '
        responsiveness:
          type: number
          minimum: 0
          maximum: 1
          example: 1
          description: Controls how responsive is the agent. Value ranging from [0,1]. Lower value means less responsive agent (wait more, respond slower), while higher value means faster exchanges (respond when it can). If unset, default value 1 will apply.
        interruption_sensitivity:
          type: number
          minimum: 0
          maximum: 1
          example: 1
          description: Controls how sensitive the agent is to user interruptions. Value ranging from [0,1]. Lower value means it will take longer / more words for user to interrupt agent, while higher value means it's easier for user to interrupt agent. If unset, default value 1 will apply. When this is set to 0, agent would never be interrupted.
        enable_backchannel:
          type: boolean
          example: true
          description: Controls whether the agent would backchannel (agent interjects the speaker with phrases like "yeah", "uh-huh" to signify interest and engagement). Backchannel when enabled tends to show up more in longer user utterances. If not set, agent will not backchannel.
        backchannel_frequency:
          type: number
          example: 0.9
          description: Only applicable when enable_backchannel is true. Controls how often the agent would backchannel when a backchannel is possible. Value ranging from [0,1]. Lower value means less frequent backchannel, while higher value means more frequent backchannel. If unset, default value 0.8 will apply.
        backchannel_words:
          type:
          - array
          - 'null'
          items:
            type: string
          example:
          - yeah
          - uh-huh
          description: Only applicable when enable_backchannel is true. A list of words that the agent would use as backchannel. If not set, default backchannel words will apply. Check out [backchannel default words](/agent/interaction-configuration#backchannel) for more details. Note that certain voices do not work too well with certain words, so it's recommended to experiment before adding any words.
        reminder_trigger_ms:
          type: number
          example: 10000
          description: If set (in milliseconds), will trigger a reminder to the agent to speak if the user has been silent for the specified duration after some agent speech. Must be a positive number. If unset, default value of 10000 ms (10 s) will apply.
        reminder_max_count:
          type: integer
          example: 2
          description: If set, controls how many times agent would remind user when user is unresponsive. Must be a non negative integer. If unset, default value of 1 will apply (remind once). Set to 0 to disable agent from reminding.
        ambient_sound:
          type:
          - string
          - 'null'
          enum:
          - coffee-shop
          - convention-hall
          - summer-outdoor
          - mountain-outdoor
          - static-noise
          - call-center
          - null
          description: 'If set, will add ambient environment sound to the call to make experience more realistic. Currently supports the following options:


            - `coffee-shop`: Coffee shop ambience with people chatting in background. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/coffee-shop.wav)

            - `convention-hall`: Convention hall ambience, with some echo and people chatting in background. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/convention-hall.wav)

            - `summer-outdoor`: Summer outdoor ambience with cicada chirping. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/summer-outdoor.wav)

            - `mountain-outdoor`: Mountain outdoor ambience with birds singing. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/mountain-outdoor.wav)

            - `static-noise`: Constant static noise. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/static-noise.wav)

            - `call-center`: Call center work noise. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/call-center.wav)

            Set to `null` to remove ambient sound from this agent.

            '
        ambient_sound_volume:
          type: number
          example: 1
          description: If set, will control the volume of the ambient sound. Value ranging from [0,2]. Lower value means quieter ambient sound, while higher value means louder ambient sound. If unset, default value 1 will apply.
        language:
          oneOf:
          - $ref: '#/components/schemas/LanguageLegacy'
          - type: array
            items:
              $ref: '#/components/schemas/Language'
          description: Specifies what language(s) the agent will operate in. Accepts either a single scalar locale (e.g. `en-US`), the legacy scalar value `multi` for multilingual support, or an array of concrete locale codes for explicit multi-locale selection (e.g. `["en-US","es-ES"]`). The array form must contain concrete locale codes only — the `multi` value is valid only as the scalar legacy form and must not appear inside an array. Single-element arrays are normalized to the equivalent scalar on output. If unset, defaults to `en-US`.
        webhook_url:
          type:
          - string
          - 'null'
          example: https://webhook-url-here
          description: The webhook for agent to listen to call events. See what events it would get at [webhook doc](/features/webhook). If set, will binds webhook events for this agent to the specified url, and will ignore the account level webhook for this agent. Set to `null` to remove webhook url from this agent.
        webhook_events:
          type:
          - array
          - 'null'
          items:
            type: string
            enum:
            - call_started
            - call_ended
            - call_analyzed
            - transcript_updated
            - transfer_started
            - transfer_bridged
            - transfer_cancelled
            - transfer_ended
          description: Which webhook events this agent should receive. If not set, defaults to call_started, call_ended, call_analyzed.
        webhook_timeout_ms:
          type: integer
          example: 10000
          description: The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply.
        boosted_keywords:
          type:
          - array
          - 'null'
          items:
            type: string
          example:
          - retell
          - kroger
          description: Provide a customized list of keywords to bias the transcriber model, so that these words are more likely to get transcribed. Commonly used for names, brands, street, etc.
        data_storage_setting:
          type: string
          enum:
          - everything
          - everything_except_pii
          - basic_attributes_only
          example: everything
          description: 'Granular setting to manage how Retell stores sensitive data (transcripts, recordings, logs, etc.).

            This replaces the deprecated `opt_out_sensitive_data_storage` field.

            - `everything`: Store all data including transcripts, recordings, and logs.

            - `everything_except_pii`: Store data without PII when PII is detected.

            - `basic_attributes_only`: Store only basic attributes; no transcripts/recordings/logs.

            If not set, default value of "everything" will apply.

            '
        data_storage_retention_days:
          type:
          - integer
          - 'null'
          minimum: 1
          maximum: 730
          example: 30
          description: Number 

# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/retell-ai/refs/heads/main/openapi/retell-ai-register-phone-call-api-openapi.yml