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.
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. 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.