Triggering Outbound Call API
The make call API allows you to utilize your telephony virtual assistant to trigger an outgoing call to any PSTN number.
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)
POST
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".
Parameter | Value |
|---|---|
to | Phone Number of Caller |
agent_id | ID of the destination virtual agent |
{
"agent_id": "string",
"to": "string"
}
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"
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"
}
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 |
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"
}
],
Please make sure to change the body tag to JSON.
{
"status_url": "string",
"hangup_on_answer_machine": false,
"session_parameters": [
{
"name": "string",
"value": "string"
}
]
"to": "string",
"agent_id": "string"
}
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"
}
]
}'
{
"session_id": "5a61cc84-4c89-4ef9-a983-5349c7112fdb",
"session_start_time": "2020-10-14T09:42:07.151657"
}
{
"status": 404,
"message": "Version information for number AGENT_NUMBER doesn't exist"
}
{
"status": 400,
"message": "Bad destination number format"
}
{
"status": 401,
"message": "Not Authorised"
}
{
"status": 500,
"message": "Failed to fetch preconfigured session information"
}