> ## 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. # Start a Call for a Conversation Route ## OpenAPI ````yaml POST /v1/voice-agents/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/call: post: summary: Initiate a call with a voice agent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CallRequest' responses: '200': description: Successful call initiation content: application/json: schema: $ref: '#/components/schemas/CallResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' security: - ApiKeyAuth: [] components: schemas: CallRequest: type: object properties: toNumber: type: string description: The number that you want to call fromNumber: type: string enum: - '+18449292835' - '+18558961879' agentDetails: $ref: '#/components/schemas/VoiceAgentRequest' description: Send agentDetails instead of voiceAgentId and params. default: {} voiceAgentId: type: string nullable: true params: type: object description: >- Params set in the voice agent's greeting message or preamble. Send when using voiceAgentId only. additionalProperties: true default: {} webhookUrl: type: string nullable: true format: uri example: https://example.com/webhook webhookAuth: $ref: '#/components/schemas/ExternalWebhookAuthScheme' anyOf: - required: - voiceAgentId - params - fromNumber - toNumber not: required: - agentDetails - required: - agentDetails - fromNumber - toNumber not: required: - voiceAgentId - params CallResponse: type: object properties: success: type: boolean default: false message: type: string default: success data: type: object properties: id: type: string title: type: string nullable: true model: type: string type: type: string processingType: type: string webhookUrl: type: string nullable: true totalCost: type: number usageTime: type: string nullable: true fromLng: type: string nullable: true toLng: type: string nullable: true mediaUrl: type: string nullable: true jobResponse: type: object nullable: true fromScript: type: string nullable: true toScript: type: string nullable: true status: type: string relevantJobId: type: string nullable: true agentDetails: $ref: '#/components/schemas/VoiceAgentResponseData' apiKeyId: type: string billingId: type: string systemModelKey: type: string nullable: true voiceAgentId: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time 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 VoiceAgentResponseData: type: object properties: id: type: string agentName: type: string greetingMessage: type: string description: type: string preamble: type: string lang: type: string pokeMessages: type: array items: type: string realTime: type: boolean silenceThreshold: type: integer interrupt: type: boolean outcome: type: string outcomeResponseShape: type: object example: type: object properties: test: type: number description: Hello world from Hamsa AI! required: - test projectId: type: string apiKeyId: type: string voiceRecordId: type: string nullable: true voiceRecord: type: object description: The voice record object which is connected to this agent. nullable: true webhookUrl: type: string nullable: true format: uri example: https://example.com/webhook webhookAuth: $ref: '#/components/schemas/ExternalWebhookAuthScheme' params: type: object description: The parameters that are created for this agent. createdAt: type: string format: date-time updatedAt: type: string format: date-time 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 ' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.