Vonage AI Studio
  • Welcome to AI Studio!
  • ✨Platform Updates
  • AI Studio
    • Create a new agent
    • NLU AI Engine Preferences
    • Agent Building Features
    • Agent Templates
      • Take Message
      • Updating Details
      • Survey
      • FAQ
      • Package Tracking
      • Caller Identification
      • Customer Service
      • Hotels
      • Appointment Management
    • Tester
    • Editor Mode & Publish
    • Reports
    • Users
    • Knowledge AI
  • Properties
    • Entities
      • System Entities List
      • Best Practices
    • Intents
      • How do we analyze user input?
      • Generate Training Data
      • System Intents
      • Intent Annotation
    • Parameters
    • Contacts
    • Tags
    • Recordings
  • Voice
    • Get started
      • Create your first conversational flow!
      • Triggering Outbound Call API
      • Sending an Outbound Call Request via Postman
      • Integration via SIP for Telephony Agents
    • Nodes
      • Start node
      • Conversation
        • Classification
          • Intent Ambiguity
        • Collect Input
          • Entity Ambiguation
        • Speak
        • Conditions
        • Listen
        • Q&A Node
      • Advanced
        • Reset Counter
        • Counter
        • Set Parameter
        • Custom Code
        • NCCO Node
      • Actions
        • Send Email
        • Call Routing
        • End Call
        • Start Recording
        • Stop Recording
        • Send SMS
      • Integrations
        • Webhook
        • Legacy SalesForce Authentication Node
          • SalesForce Authentication
            • How to create a SalesForce Connected App
        • SalesForce Actions
        • Generative AI
          • Setting up Generative AI Node Integration
          • Migrating from the GenAI node to Knowledge AI
      • Flow Control
        • Context Switch
        • Flows
    • Events
  • WhatsApp
    • Get started
      • Create your first conversational flow!
      • Triggering an outbound WhatsApp virtual agent
    • Nodes
      • Start node
      • Conversation
        • Collect Input
          • Entity Ambiguation
        • Classification
          • Intent Ambiguity
        • Send Message
        • Conditions
      • Advanced
        • Reset Counter
        • Counter
        • Set Parameter
        • Custom Code
      • Actions
        • Send Email
        • End Conversation
        • Send SMS
        • Live Agent Routing
      • Integrations
        • Webhook
        • Legacy SalesForce Authentication Node
          • SalesForce Authentication
            • How to create a SalesForce Connected App
        • SalesForce Actions
        • Generative AI
          • Setting up Generative AI Node Integration
          • Endless FAQs on WhatsApp With Generative AI and AI Studio
      • Flow Control
        • Context Switch
        • Flows
    • Events
  • SMS
    • Get started
      • Create your first conversational flow!
      • Triggering an outbound SMS Virtual Agent
    • Nodes
      • Start node
      • Conversation
        • Classification
          • Intent Ambiguity
        • Conditions
        • Send Message
        • Collect Input
          • Entity Ambiguation
      • Advanced
        • Reset Counter
        • Counter
        • Set Parameter
        • Custom Code
      • Actions
        • Send Email
        • End Conversation
        • Send SMS
        • Live Agent Routing
      • Integrations
        • Webhook
        • Legacy SalesForce Authentication Node
          • SalesForce Authentication
            • How to create a SalesForce Connected App
        • SalesForce Actions
        • Generative AI
          • Setting up Generative AI Node Integration
          • Use Case Example: Gym Business
      • Flow Control
        • Context Switch
        • Flows
    • Events
  • HTTP
    • Get started
      • Create your first conversational flow!
    • Nodes
      • Start node
      • Conversation
        • Classification
          • Intent Ambiguity
        • Collect Input
          • Entity Ambiguation
        • Send Message
        • Conditions
      • Advanced
        • Reset Counter
        • Counter
        • Set Parameter
        • Custom Code
      • Action
        • Send Email
        • Send SMS
        • Live Agent Routing
          • Websockets connections for Live agent Routing
      • Integrations
        • Webhook
        • Legacy SalesForce Authentication Node
          • SalesForce Authentication
            • How to create a SalesForce Connected App
        • SalesForce Actions
        • Generative AI
          • Setting up Generative AI Node Integration
          • Use case Example : Online Shopping
      • Flow Control
        • Context Switch
        • Flows
    • Events
  • API Integration
    • Authentication
    • Insights
  • There's more
    • FAQs
    • Languages Available
Powered by GitBook
On this page
  • How to prepare your Outbound Call Query
  • Endpoint (mandatory)
  • Method (mandatory)
  • Headers (mandatory)
  • Body (mandatory)
  • Example Query
  • Successful Call Response
  • Potential Errors

Was this helpful?

  1. Voice
  2. Get started

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.

PreviousCreate your first conversational flow!NextSending an Outbound Call Request via Postman

Last updated 1 year ago

Was this helpful?

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.

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.

  • 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!

How to prepare your Outbound Call Query

Endpoint (mandatory)

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 Caller/SIP Endpoint

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"

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

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": "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"
}

If you require an increased limit, please email with the following details:-

For Agents deployed in EU region -->

For Agents deployed in US region -->

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 .

support@aistudio.vonage.com
https://studio-api-eu.ai.vonage.com/telephony/make-call
https://studio-api-us.ai.vonage.com/telephony/make-call
example query