# Triggering Outbound Call API {% hint style="info" %} *For the launch of the outbound call to work, make sure you have published your agent and that it has a phone number attached to it.* {% endhint %} {% hint style="danger" %} **Are you using postman?** *When using curly braces in the query parameters, make sure you encode the content of your curly braces. If sent without the encoding, your request will return empty.* {% endhint %} ![](/files/KgtmuTwa7pXnttxrRash) {% hint style="warning" %} **Are you within the limits?** *Studio’s outbound call limits that is! We currently only allow one call/session per second however if your virtual agent needs to make more calls we can increase the limit up to 5 outbound calls per second.* *If you require an increased limit, please email* [*support@aistudio.vonage.com*](mailto:support@aistudio.vonage.com) *with the following details:-* * *API key* * *Agent ID(/s)* * *Increase request: You can choose to increase your limit to 3 or 5 calls per second* *Once you receive confirmation from our teams that your request has been processed, please publish your agents and wait for about 5 minutes before you start triggering any new outbound calls.* *Please note that if your agent is not approved for a higher limit, any call made over the 1 call per second limit will fail and return a 429 error!* {% endhint %} ## How to prepare your Outbound Call Query ### Endpoint (mandatory) For Agents deployed in **EU** region --> [`https://studio-api-eu.ai.vonage.com/telephony/make-call`](https://studio-api-eu.ai.vonage.com/telephony/make-call) For Agents deployed in **US** region --> [`https://studio-api-us.ai.vonage.com/telephony/make-call` ]() ### Method (mandatory) POST ### Headers (mandatory) X-Vgai-Key (Don't forget to add the value of the Vgai key after you generated it) {% hint style="info" %} *You can find the X-Vgai-Key on the top right of your canvas. Click on the "user" icon, and then "Generate API Key".* {% endhint %} ![](/files/-MdNFGihR9dA1NJmijKE) ### Body (mandatory) #### Destination Parameters (mandatory) | Parameter | Value | | :-------: | :---------------------------------: | | to | Phone Number of Caller/SIP Endpoint | | agent\_id | ID of the destination virtual agent | To route to phone numbers make sure to enter the phone number with the country code without any special characters. In cases of SIP routing, the value must include the SIP address within the body as mentioned in this [example query](https://studio.docs.ai.vonage.com/voice/get-started/telephony#example-query). ``` { "agent_id": "string", "to": "string" } ``` {% hint style="info" %} *When you send the **`agent_id`**, it will initiate a session from the published number of the agent.* *If the agent does not exist or hasn't been published , you will get an error stating either that "ID {{AGENT\_ID}} is not an ID to any agent or published version" or "published version for Agent {{AGENT\_ID}} was not found"* {% endhint %} #### status\_url (optional) If the recipient cannot pick up the call for any reason, we will send a response to a designated callback URL Add the relevant endpoint that a response is sent to in case the callee didn't manage to pick up the call. Example Response payload: ``` { "agent_id": "string", "to": "972542233016", "conversation_uuid": "CON-4ee2e523-4ee13-4e98-ae94-e6e3e1ab9ac6", "status": "busy", "timestamp": "2022-05-31T06:40:45.475Z" } ``` Currently we support the following values to be attached to Status:- * `cancelled` - Call cancelled by the originating source before it was answered. * `rejected`- Call attempt was rejected by the destination. * `busy` - Destination is on the line/busy with another caller. * `timeout` - Call timed out before it was answered. * `failed`- Call failed before reaching the destination #### hangup\_on\_answer\_machine (optional) *\[BETA Testing Phase]* We are able to recognize when an answering machine picks up the call and the call is going to be immediately disconnected. Add the following parameters to your request: | parameter | value | | --------------------------- | ----- | | hangup\_on\_answer\_machine | false | #### session\_parameters (optional) You can send parameters to the virtual agent prior to initiating the call, e.g. the name of the caller. The agent can then greet the caller with his name. | Parameter | Value | | :----------: | :----------: | | CALLER\_NAME | Diane Miller | ``` "session_parameters": [ { "name": "CALLER_NAME", "value": "Diane Miller" } ], ``` ### Example Query {% hint style="warning" %} *Please make sure to change the body tag to JSON.* {% endhint %} ``` { "status_url": "string", "hangup_on_answer_machine": false, "session_parameters": [ { "name": "string", "value": "string" } ] "to": "sip:sipnumber@sipaddress", "agent_id": "string" } ``` ## Successful Call Response #### Curl Example Request ``` curl --location --request POST 'https://stairway.ai.vonage.com/telephony/make-call' \ --header 'X-Vgai-Key: Cuub4r22PXb0zYzJ2dt82KUZLKjo0z7' \ --header 'Content-Type: application/json' \ --data-raw '{ "agent_id": "60c09d70e6a68858f4220848", "to": "9725411116037", "hangup_on_answer_machine": false, "session_parameters":[ { "name": "PROPERTY_VALUE", "value": "500" } ] }' ``` #### Response ``` { "session_id": "5a61cc84-4c89-4ef9-a983-5349c7112fdb", "session_start_time": "2020-10-14T09:42:07.151657" } ``` ## Potential Errors #### Agent doesn't exist ``` { "status": 404, "message": "Version information for number AGENT_NUMBER doesn't exist" } ``` #### Bad number format ``` { "status": 400, "message": "Bad destination number format" } ``` #### **Not Authorised** ``` { "status": 401, "message": "Not Authorised" } ``` #### **The preconfigured session doesn't exist** ``` { "status": 500, "message": "Failed to fetch preconfigured session information" } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://studio.docs.ai.vonage.com/voice/get-started/telephony.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.