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

# Create an Outbound Call



## OpenAPI

````yaml POST /v1/voice-agents/phone-number/call
openapi: 3.0.1
info:
  title: Hamsa API
  description: Trying out our transcription and media-to-text APIs
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v1/voice-agents/phone-number/call:
    post:
      summary: Call Voice Agent using Twilio custom phone number.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallPhoneNumberRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallPhoneNumberResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CallPhoneNumberRequest:
      type: object
      properties:
        toNumber:
          type: string
          description: The number that you want to call
        phoneNumber:
          type: string
          example: '+1234567890'
          pattern: ^\+[1-9]\d{1,14}$
        agentDetails:
          $ref: '#/components/schemas/VoiceAgentRequest'
          description: Send agentDetails instead of voiceAgentId and params.
          default:
            agentName: ''
        voiceAgentId:
          type: string
          nullable: true
          example: d949f13f-40d2-4e48-ac86-b66633070603
        params:
          type: object
          description: >-
            Overriding params set in the voice agent's greeting message or
            preamble. Send when using voiceAgentId only.
          additionalProperties: true
          default: {}
      anyOf:
        - required:
            - voiceAgentId
            - params
            - phoneNumber
            - toNumber
        - required:
            - agentDetails
            - phoneNumber
            - toNumber
    CallPhoneNumberResponse:
      type: object
      properties:
        success:
          type: boolean
          default: false
        message:
          type: string
          default: success
        data:
          type: object
          properties:
            voiceAgentId:
              type: string
              example: d949f13f-40d2-4e48-ac86-b66633070603
              description: The voice agent Id attached to the phone number
            jobId:
              type: string
              example: d949f13f-40d2-4e48-ac86-b66633070603
              description: The call job Id
    ErrorSchema:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    VoiceAgentRequest:
      type: object
      properties:
        agentName:
          type: string
        greetingMessage:
          description: >-
            Greeting Message can be customized by adding params like: {{name}},
            to make the message more personal!
          type: string
          default: Hello, how can I help you today?
        preamble:
          description: >-
            Preamble can be customized by adding params like: {{agentName}}, to
            make the prompt more specific and context aware!
          type: string
          default: You are a helpful assistant that will answer users questions.
        lang:
          type: string
          enum:
            - ar
            - en
          default: ar
        pokeMessages:
          description: The messages to say to the user when he doesn't respond!
          type: array
          items:
            type: string
          default: []
        realTime:
          type: boolean
          default: false
        silenceThreshold:
          type: integer
          default: 800
          minimum: 1
          description: >-
            The silence threshold in milliseconds. Minimum value is 1
            millisecond.
        interrupt:
          type: boolean
          default: false
        outcome:
          description: >-
            A prompt to take the conversation and transform it to anything you
            like, like creating an article out of the conversation!
          type: string
          default: null
        webhookUrl:
          type: string
          nullable: true
          format: uri
          example: https://example.com/webhook
        webhookAuth:
          $ref: '#/components/schemas/ExternalWebhookAuthScheme'
        outcomeResponseShape:
          type: object
          title: Outcome Response Schema
          description: >-
            Recursive OpenAPI-style shape with 'type', 'properties', 'required',
            'items', ...etc. Please refer to the `OpenAPI Outcome Response
            Instructions` above for more information.
          example:
            type: object
            properties:
              test:
                type: number
                description: Hello world from Hamsa AI!
            required:
              - test
        voiceId:
          description: >-
            For trying voices and choosing one by yourself, or event cloning a
            voice, please visit Hamsa Agents platform voices tab
            [here](https://agents.tryhamsa.com/app/voices).
          type: string
          enum:
            - ab55c68b-091b-43b4-a55a-0be82093cd23
            - 79f81a3b-10f7-4eea-b0aa-5bd0b887d8cd
            - f87b58a6-dd88-4f77-86e4-10099e8412c8
            - 35189a1c-afbd-4ab7-9aa2-1af88c70ac63
            - 88d45604-12e9-4f7a-93bf-e16cf04c9214
            - 2ef6405e-7313-4b5e-b738-b0536ed0a36a
            - 9bead147-7ae5-47aa-80d3-f54668568a69
            - e2803890-f4dd-46f7-bfc6-1d3dc761c8ae
            - ac5ca565-175c-48d8-98dc-2fccc906cf4b
            - fb4d10c0-295d-43a9-9d8e-8775144b4b23
            - 3c249172-a61a-4a72-9375-1591b73d7ef6
            - 21f9d3fc-ae8b-41a2-9165-a3186433ae3c
            - 8e9f526c-eb30-417d-9e7a-65f704917fcc
            - 8a97dfe8-fe9d-40c5-8f94-7bf9b142e254
        tools:
          type: object
          properties:
            genderDetection:
              type: boolean
              default: false
            smartCallEnd:
              type: boolean
              default: false
        params:
          description: >-
            Set the params you define in the greeting message or preamble fields
            here, the key is the same as the param and the value is the param
            value. Press 'Add new property' below to set the param name then
            press enter, after that add the value.
          type: object
          default: {}
      required:
        - agentName
    ExternalWebhookAuthScheme:
      type: object
      description: >-
        Authorization header to be sent in this format: `Authorization:
        [authKey] [authSecret]`
      properties:
        authKey:
          type: string
          example: Token
          nullable: true
        authSecret:
          type: string
          example: Secret
          nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.