Outbound Call API
Objective
The make call API allows you to utilize your virtual assistant to triggers an outgoing call to any PSTN number
Applies To
- Vonage AI Studio
Procedure
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.
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.
.png?alt=media&token=03d6c8e0-6100-4082-b79b-fbf1e06e2ede)
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
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)
You can find the X-Vgai-Key on the top right of your canvas. Click on the "user" icon, and then "Generate API Key".
Body (mandatory)
Destination Parameters (mandatory)
| parameter | value |
| to | phone number of the callee |
| agent id | ID of the virtual agent |
| from | phone number of the virtual assistant |
{
"from": "string",
"agent_id": "string",
"to": "string"
}
You can choose to either use
from or agent_id to send your request.If you choose to use
from, the request will try to get the agent connected to the number you added as the value and create a phone call from this number. If didn’t succeed we will get an error Phone X is not attached to any agent or published version
If you choose to send
agent_id , it will create a phone call from the published number of the agent. If you try to send both, it will create a phone call based on the
from number. If the number is not the published number of the agent, it will create a phone call with No Caller ID.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:
{
"from": "972337287459",
"to": "972542233016",
"conversation_uuid": "CON-4ee2e523-4ee13-4e98-ae94-e6e3e1ab9ac6",
"status": "busy",
"timestamp": "2022-05-31T06:40:45.475Z"
}
hangup_on_answer_machine (optional)
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
Please make sure to change the body tag to JSON.
{
"status_url": "string",
"hangup_on_answer_machine": false,
"session_parameters": [
{
"name": "string",
"value": "string"
}
],
"from": "string",
"to": "string",
"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 '{
"from": "4420382243509",
"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"
}
Comments
0 comments
Article is closed for comments.