Skip to main content
Docs menu: Placing outbound calls

Guides

Placing outbound calls

Queue a call from one of your agents, choose the script it follows, and pass the details the agent needs for that call.

One request to POST /outbound queues one call. Your system decides when to call and who to call; the agent handles the conversation and Telvana reports the result.

curl -X POST "https://api.telvana.com/outbound" \
  -H "x-api-key: $TELVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15557654321",
    "outboundPromptId": "clx8y9z1a2b3c4d5e6f7g8h9i",
    "variables": {
      "firstName": "Dana",
      "pickupTime": "2:30 PM"
    }
  }'

The fields

from is the agent's phone number, as listed on the portal's Phone Numbers page. The number decides which agent places the call, and it has to belong to the workspace your API key is for.

to is the number to call. Today the API accepts +1 numbers (the US and Canada). Write both numbers in E.164 form, such as +15557654321.

outboundPromptId picks the outbound prompt, the script the agent follows on this call. Leave it out and the agent uses its first outbound prompt. An agent can have several, for example one for appointment confirmations and one for reminders.

variables is an object of strings that fills placeholders in the prompt. If the prompt says Hi {{firstName}}, I'm calling to confirm your pickup at {{pickupTime}}, the request above makes the agent say "Hi Dana" and use 2:30 PM. Send every variable the prompt uses, and send values as strings, including numbers and dates. The same variables come back in the call's webhook, so you can also use them to carry your own ids.

What the response means

A 200 means the call is queued, not that anyone answered:

{
  "data": {
    "from": "+15551234567",
    "to": "+15557654321",
    "conversationId": "clx8y9z1a2b3c4d5e6f7g8h9i",
    "outboundPromptId": "clx8y9z1a2b3c4d5e6f7g8h9i",
    "variables": { "firstName": "Dana", "pickupTime": "2:30 PM" }
  },
  "message": "Request queued for outbound processing"
}

Keep conversationId. The finished call is stored under that id, and the webhook for the call carries it.

After the call

Telvana dials the call and the agent talks with whoever answers. When the call ends, Telvana writes the conversation with its transcript, summary, sentiment and tags. The call's webhook also reports its disposition, such as COMPLETED, VOICEMAIL or FAILED.

A call that never connects still gets a conversation under the same id, with a duration of 0, sentiment N_A and, in the webhook, disposition set to FAILED. Telvana makes one attempt per request. If you want to try the number again, send a new request when your own rules say to.

Get results by webhook or by reading the conversation.

Calling rules and the do-not-call list

Every call also follows your workspace's calling rules (portal: Settings, Calling) and its do-not-call list (Settings, Do-Not-Call List).

  • While calls are turned off for the workspace, POST /outbound answers 409 with the code CALLS_DISABLED and queues nothing. Calls already waiting stay queued until calls are turned back on.
  • A request to a number on the workspace's do-not-call list answers 409 with the code DO_NOT_CALL. A number added to the list while its call is waiting is not called.
  • A call-pause schedule, or a US public holiday the workspace pauses on, doesn't refuse the request. The call is queued and goes out when the pause ends, and the 200 answer's message says so: Request queued for outbound processing. Outbound calls are paused by the workspace's call-pause schedule, so it goes out when the pause ends.
  • An agent with runDoNotCallDetection on (see the Agents reference) tags a call do_not_call when the person asks not to be called again, and puts the number on the list. It is off by default.

The list is the workspace's own. Telvana does not check numbers against the National Do Not Call Registry.

Find an agent's id and prompts

The agent's id is in its portal address: app.telvana.com/agents/<agentId>. List its outbound prompts with:

curl "https://api.telvana.com/agents/<agentId>/outbound-prompts" \
  -H "x-api-key: $TELVANA_API_KEY"

Each prompt in the response has the id you pass as outboundPromptId.

Create a prompt through the API

Prompts can come from your own system too. Create one with a title and instructions, then use its id in calls:

curl -X POST "https://api.telvana.com/agents/<agentId>/outbound-prompts" \
  -H "x-api-key: $TELVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pickup confirmation",
    "instructions": "You are calling {{firstName}} to confirm a pickup at {{pickupTime}}. Confirm the time, or ask what time works better and note it."
  }'

The full list of prompt fields, including the opening line, is in the Agents reference.

If a request fails

A request with a malformed number or a missing field gets a 400 that names the field. If your workspace has reached its monthly usage limit, the call is refused with a 403 and the code USAGE_LIMIT_EXCEEDED. If calls are turned off for the workspace or the number is on its do-not-call list, the call is refused with a 409 and the code CALLS_DISABLED or DO_NOT_CALL (see calling rules). See Errors for the format.

If your request times out on your side, don't send it again straight away. The first request may have been queued, and a second one would call the same person twice. Once enough time has passed for a call to finish, look for a conversation with that humanPhoneNumber in the conversation list before you decide.