> ## Documentation Index
> Fetch the complete documentation index at: https://doc.rapida.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# create-phone-call

> Starts one outbound phone call using the configured assistant and returns the created conversation identifier.



## OpenAPI

````yaml /openapi/talk-api.yaml post /v1/talk/create-phone-call
openapi: 3.0.3
info:
  title: Rapida Assistant API
  version: 0.1.0
  description: >-
    REST endpoints for creating assistants, managing assistant deployments, and
    starting outbound assistant phone calls.
servers:
  - url: https://assistant-01.in.rapida.ai
    description: Rapida managed assistant API
  - url: https://assistant-01.us.rapida.ai
    description: Local assistant API
security:
  - ProjectApiKeyHeader: []
  - ProjectApiKeyQuery: []
  - AuthenticationHeader: []
tags:
  - name: assistants
    x-group: Assistants
    description: Assistant management APIs.
  - name: assistant-deployments
    x-group: Assistant deployments
    description: Assistant deployment management APIs.
  - name: calls
    x-group: Calls
    description: Outbound call APIs.
paths:
  /v1/talk/create-phone-call:
    post:
      tags:
        - calls
      summary: create-phone-call
      description: >-
        Starts one outbound phone call using the configured assistant and
        returns the created conversation identifier.
      operationId: createPhoneCall
      parameters:
        - $ref: '#/components/parameters/ClientSourceHeader'
        - $ref: '#/components/parameters/AuthIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePhoneCallRequest'
            examples:
              basic:
                summary: Start a phone call
                value:
                  assistant:
                    assistantId: '2227823180112723968'
                    version: latest
                  toNumber: '+14155550123'
                  fromNumber: '+14155550100'
                  metadata:
                    customerId: cust_123
                  args:
                    customerName: Jane
                  options:
                    priority: standard
      responses:
        '200':
          description: Outbound phone call request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePhoneCallResponse'
              examples:
                accepted:
                  summary: Call accepted
                  value:
                    code: 200
                    success: true
                    data:
                      id: '2230142097179373568'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingToNumber:
                  summary: Missing destination number
                  value:
                    code: 400
                    success: false
                    error:
                      errorCode: '1002003'
                      errorMessage: missing toNumber parameter
                      humanMessage: Please provide the required toNumber parameter.
                invalidAssistant:
                  summary: Invalid assistant
                  value:
                    code: 400
                    success: false
                    error:
                      errorCode: '1002004'
                      errorMessage: invalid assistant parameter
                      humanMessage: Please provide a valid assistant.
        '403':
          description: Unauthenticated request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthenticated:
                  summary: Missing or invalid API key
                  value:
                    code: 403
                    success: false
                    error:
                      errorCode: '1002002'
                      errorMessage: unauthenticated request
                      humanMessage: >-
                        Unauthenticated request, please try again with valid
                        authentication.
        '500':
          description: Failed to initiate outbound call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                callFailed:
                  summary: Outbound call failed
                  value:
                    code: 500
                    success: false
                    error:
                      errorCode: '1002008'
                      errorMessage: unable to initiate outbound call
                      humanMessage: >-
                        Unable to initiate outbound call, please try again
                        later.
components:
  parameters:
    ClientSourceHeader:
      name: x-client-source
      in: header
      required: false
      schema:
        type: string
        default: sdk
        enum:
          - sdk
      description: Client source identifier. SDK clients send this automatically.
    AuthIdHeader:
      name: x-auth-id
      in: header
      required: false
      schema:
        type: string
      description: Optional user identifier to propagate with the request.
  schemas:
    CreatePhoneCallRequest:
      type: object
      required:
        - assistant
        - toNumber
      properties:
        assistant:
          $ref: '#/components/schemas/AssistantDefinition'
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Arbitrary metadata stored with the conversation for tracking and
            analytics.
          example:
            customerId: cust_123
        args:
          type: object
          additionalProperties: true
          description: Runtime arguments made available to the assistant.
          example:
            customerName: Jane
        options:
          type: object
          additionalProperties: true
          description: Runtime options for call behavior and configuration.
          example:
            priority: standard
        fromNumber:
          type: string
          description: >-
            Caller ID phone number in E.164 format. If omitted, Rapida uses the
            configured default.
          example: '+14155550100'
        toNumber:
          type: string
          description: Destination phone number in E.164 format.
          example: '+14155550123'
    CreatePhoneCallResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 200
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/AssistantConversation'
        error:
          $ref: '#/components/schemas/Error'
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 400
        success:
          type: boolean
          example: false
        error:
          $ref: '#/components/schemas/Error'
    AssistantDefinition:
      type: object
      required:
        - assistantId
      properties:
        assistantId:
          $ref: '#/components/schemas/Uint64String'
          description: Assistant ID to use for the call.
        version:
          type: string
          description: Assistant version. Use latest to run the latest published version.
          example: latest
    AssistantConversation:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uint64String'
        userId:
          $ref: '#/components/schemas/Uint64String'
        assistantId:
          $ref: '#/components/schemas/Uint64String'
        name:
          type: string
        projectId:
          $ref: '#/components/schemas/Uint64String'
        organizationId:
          $ref: '#/components/schemas/Uint64String'
        source:
          type: string
        createdBy:
          $ref: '#/components/schemas/Uint64String'
        updatedBy:
          $ref: '#/components/schemas/Uint64String'
        user:
          $ref: '#/components/schemas/User'
        assistantProviderModelId:
          $ref: '#/components/schemas/Uint64String'
        assistantConversationMessage:
          type: array
          items:
            $ref: '#/components/schemas/AssistantConversationMessage'
        identifier:
          type: string
        status:
          type: string
        createdDate:
          type: string
          format: date-time
        updatedDate:
          type: string
          format: date-time
        contexts:
          type: array
          items:
            $ref: '#/components/schemas/AssistantConversationContext'
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/Metric'
        arguments:
          type: array
          items:
            $ref: '#/components/schemas/Argument'
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/Metadata'
        options:
          type: array
          items:
            $ref: '#/components/schemas/Metadata'
        direction:
          type: string
        recordings:
          type: array
          items:
            $ref: '#/components/schemas/AssistantConversationRecording'
        telephonyEvents:
          type: array
          items:
            $ref: '#/components/schemas/AssistantConversationTelephonyEvent'
    Error:
      type: object
      description: >
        Platform error response details. `errorCode` is a stable platform error
        code.

        See `PlatformErrorCode` for documented code/message mappings.
      properties:
        errorCode:
          $ref: '#/components/schemas/PlatformErrorCode'
          description: Stable platform error code.
        errorMessage:
          type: string
          description: Stable client-safe error message.
          example: missing toNumber parameter
        humanMessage:
          type: string
          description: Client-safe human-readable message.
          example: Please provide the required toNumber parameter.
    Uint64String:
      type: string
      pattern: ^[0-9]+$
      example: '2227823180112723968'
    User:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uint64String'
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
        status:
          type: string
        createdDate:
          type: string
          format: date-time
    AssistantConversationMessage:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uint64String'
        assistantConversationId:
          $ref: '#/components/schemas/Uint64String'
        role:
          type: string
        content:
          type: string
        createdDate:
          type: string
          format: date-time
        updatedDate:
          type: string
          format: date-time
    AssistantConversationContext:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uint64String'
        assistantConversationId:
          $ref: '#/components/schemas/Uint64String'
        key:
          type: string
        value:
          type: string
        createdDate:
          type: string
          format: date-time
        updatedDate:
          type: string
          format: date-time
    Metric:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        description:
          type: string
    Argument:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uint64String'
        name:
          type: string
        value:
          type: string
    Metadata:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uint64String'
        key:
          type: string
        value:
          type: string
    AssistantConversationRecording:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uint64String'
        assistantRecordingUrl:
          type: string
          format: uri
        userRecordingUrl:
          type: string
          format: uri
        conversationRecordingUrl:
          type: string
          format: uri
    AssistantConversationTelephonyEvent:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uint64String'
        assistantConversationId:
          $ref: '#/components/schemas/Uint64String'
        provider:
          type: string
        eventType:
          type: string
        payload:
          type: object
          additionalProperties: true
        createdDate:
          type: string
          format: date-time
        updatedDate:
          type: string
          format: date-time
    PlatformErrorCode:
      type: string
      pattern: ^[0-9]+$
      description: >
        Stable platform error code.


        Create Assistant:

        - `1001001`: invalid request - Invalid request.

        - `1001002`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1001003`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1001004`: missing name parameter - Please provide the required name
        parameter.

        - `1001005`: missing assistant_provider parameter - Please provide the
        required assistantProvider parameter.

        - `1001006`: invalid assistant_provider parameter - Please provide
        exactly one assistant provider.

        - `1001007`: missing model_provider_name parameter - Please provide the
        required modelProviderName parameter.

        - `1001008`: missing agent_kit_url parameter - Please provide the
        required agentKitUrl parameter.

        - `1001009`: missing websocket_url parameter - Please provide the
        required websocketUrl parameter.

        - `1001010`: invalid source_identifier parameter - Please provide a
        valid sourceIdentifier parameter.

        - `1001011`: unable to create assistant - Unable to create assistant,
        please try again later.

        - `1001012`: invalid assistant provider template - Invalid assistant
        provider template.

        - `1001013`: unable to create assistant provider model - Unable to
        create assistant provider model, please try again later.

        - `1001014`: unable to attach assistant provider model - Unable to
        attach assistant provider model, please try again later.

        - `1001015`: unable to create assistant provider agentkit - Unable to
        create assistant provider agentkit, please try again later.

        - `1001016`: unable to attach assistant provider agentkit - Unable to
        attach assistant provider agentkit, please try again later.

        - `1001017`: unable to create assistant provider websocket - Unable to
        create assistant provider websocket, please try again later.

        - `1001018`: unable to attach assistant provider websocket - Unable to
        attach assistant provider websocket, please try again later.

        - `1001019`: invalid knowledge_id parameter - Please provide a valid
        knowledgeId parameter.

        - `1001020`: invalid reranker_model_provider_id parameter - Please
        provide a valid rerankerModelProviderId parameter.

        - `1001021`: unable to create assistant tools - Unable to create
        assistant tools, please try again later.

        - `1001022`: unable to create assistant knowledge - Unable to create
        assistant knowledge, please try again later.

        - `1001023`: unable to create assistant tags - Unable to create
        assistant tags, please try again.


        Create Phone Call:

        - `1002001`: invalid request - Invalid request.

        - `1002002`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1002003`: missing toNumber parameter - Please provide the required
        toNumber parameter.

        - `1002004`: invalid assistant parameter - Please provide a valid
        assistant.

        - `1002005`: invalid metadata parameter - Please provide valid metadata.

        - `1002006`: invalid arguments parameter - Please provide valid
        arguments.

        - `1002007`: invalid options parameter - Please provide valid options.

        - `1002008`: unable to initiate outbound call - Unable to initiate
        outbound call, please try again later.


        Create Bulk Phone Call:

        - `1003001`: invalid request - Invalid request.

        - `1003002`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1003003`: missing phone_calls parameter - Please provide at least one
        phone call.

        - `1003004`: missing toNumber parameter - Please provide the required
        toNumber parameter.

        - `1003005`: invalid assistant parameter - Please provide a valid
        assistant.

        - `1003006`: invalid metadata parameter - Please provide valid metadata.

        - `1003007`: invalid arguments parameter - Please provide valid
        arguments.

        - `1003008`: invalid options parameter - Please provide valid options.

        - `1003009`: unable to initiate outbound call - Unable to initiate
        outbound call, please try again later.


        Create Assistant Debugger Deployment:

        - `1004001`: invalid request - Invalid request.

        - `1004002`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1004003`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1004004`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1004005`: unable to create assistant debugger deployment - Unable to
        create assistant debugger deployment, please try again later.

        - `1004006`: invalid audio provider parameter - Please provide a valid
        audioProvider parameter.

        - `1004007`: invalid ideal_timeout parameter - Please provide
        idealTimeout between 15 and 120 seconds.

        - `1004008`: invalid ideal_timeout_backoff parameter - Please provide
        idealTimeoutBackoff between 0 and 5 times.

        - `1004009`: invalid max_session_duration parameter - Please provide
        maxSessionDuration between 180 and 600 seconds.


        Create Assistant Phone Deployment:

        - `1005001`: invalid request - Invalid request.

        - `1005002`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1005003`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1005004`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1005005`: unable to create assistant phone deployment - Unable to
        create assistant phone deployment, please try again later.

        - `1005006`: invalid audio provider parameter - Please provide a valid
        audioProvider parameter.

        - `1005007`: invalid ideal_timeout parameter - Please provide
        idealTimeout between 15 and 120 seconds.

        - `1005008`: invalid ideal_timeout_backoff parameter - Please provide
        idealTimeoutBackoff between 0 and 5 times.

        - `1005009`: invalid max_session_duration parameter - Please provide
        maxSessionDuration between 180 and 600 seconds.

        - `1005010`: missing phone_provider_name parameter - Please provide the
        required phoneProviderName parameter.


        Create Assistant API Deployment:

        - `1006001`: invalid request - Invalid request.

        - `1006002`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1006003`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1006004`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1006005`: unable to create assistant api deployment - Unable to
        create assistant api deployment, please try again later.

        - `1006006`: invalid audio provider parameter - Please provide a valid
        audioProvider parameter.

        - `1006007`: invalid ideal_timeout parameter - Please provide
        idealTimeout between 15 and 120 seconds.

        - `1006008`: invalid ideal_timeout_backoff parameter - Please provide
        idealTimeoutBackoff between 0 and 5 times.

        - `1006009`: invalid max_session_duration parameter - Please provide
        maxSessionDuration between 180 and 600 seconds.


        Create Assistant Webplugin Deployment:

        - `1007001`: invalid request - Invalid request.

        - `1007002`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1007003`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1007004`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1007005`: unable to create assistant web plugin deployment - Unable
        to create assistant web plugin deployment, please try again later.

        - `1007006`: invalid audio provider parameter - Please provide a valid
        audioProvider parameter.

        - `1007007`: invalid ideal_timeout parameter - Please provide
        idealTimeout between 15 and 120 seconds.

        - `1007008`: invalid ideal_timeout_backoff parameter - Please provide
        idealTimeoutBackoff between 0 and 5 times.

        - `1007009`: invalid max_session_duration parameter - Please provide
        maxSessionDuration between 180 and 600 seconds.


        Create Assistant WhatsApp Deployment:

        - `1008001`: invalid request - Invalid request.

        - `1008002`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1008003`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1008004`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1008005`: unable to create assistant whatsapp deployment - Unable to
        create assistant whatsapp deployment, please try again later.

        - `1008006`: invalid ideal_timeout parameter - Please provide
        idealTimeout between 15 and 120 seconds.

        - `1008007`: invalid ideal_timeout_backoff parameter - Please provide
        idealTimeoutBackoff between 0 and 5 times.

        - `1008008`: invalid max_session_duration parameter - Please provide
        maxSessionDuration between 180 and 600 seconds.

        - `1008009`: missing whatsapp_provider_name parameter - Please provide
        the required whatsappProviderName parameter.


        Get Assistant Debugger Deployment:

        - `1009001`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1009002`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1009003`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1009004`: unable to get assistant debugger deployment - Unable to get
        assistant debugger deployment, please try again later.


        Get Assistant Phone Deployment:

        - `1010001`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1010002`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1010003`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1010004`: unable to get assistant phone deployment - Unable to get
        assistant phone deployment, please try again later.


        Get Assistant API Deployment:

        - `1011001`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1011002`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1011003`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1011004`: unable to get assistant api deployment - Unable to get
        assistant api deployment, please try again later.


        Get Assistant Webplugin Deployment:

        - `1012001`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1012002`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1012003`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1012004`: unable to get assistant webplugin deployment - Unable to
        get assistant webplugin deployment, please try again later.


        Get Assistant WhatsApp Deployment:

        - `1013001`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1013002`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1013003`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1013004`: unable to get assistant whatsapp deployment - Unable to get
        assistant whatsapp deployment, please try again later.


        Get All Assistant Debugger Deployments:

        - `1014001`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1014002`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1014003`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1014004`: invalid request - Invalid request.

        - `1014005`: unable to get assistant debugger deployments - Unable to
        get assistant debugger deployments, please try again later.


        Get All Assistant Phone Deployments:

        - `1015001`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1015002`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1015003`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1015004`: invalid request - Invalid request.

        - `1015005`: unable to get assistant phone deployments - Unable to get
        assistant phone deployments, please try again later.


        Get All Assistant API Deployments:

        - `1016001`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1016002`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1016003`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1016004`: invalid request - Invalid request.

        - `1016005`: unable to get assistant api deployments - Unable to get
        assistant api deployments, please try again later.


        Get All Assistant Webplugin Deployments:

        - `1017001`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1017002`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1017003`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1017004`: invalid request - Invalid request.

        - `1017005`: unable to get assistant webplugin deployments - Unable to
        get assistant webplugin deployments, please try again later.


        Get All Assistant WhatsApp Deployments:

        - `1018001`: unauthenticated request - Unauthenticated request, please
        try again with valid authentication.

        - `1018002`: missing authentication scope - Unauthenticated request,
        please try again with valid authentication.

        - `1018003`: invalid assistant_id parameter - Please provide a valid
        assistantId parameter.

        - `1018004`: invalid request - Invalid request.

        - `1018005`: unable to get assistant whatsapp deployments - Unable to
        get assistant whatsapp deployments, please try again later.
      example: '1002003'
  securitySchemes:
    ProjectApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key from Rapida credentials.
    ProjectApiKeyQuery:
      type: apiKey
      in: query
      name: x-api-key
      description: API key from Rapida credentials.
    AuthenticationHeader:
      type: apiKey
      in: header
      name: Authentication
      description: API key from Rapida credentials.

````