Outbound calls

POST /v1/calls/outbound places one live phone call: it dials to from one of your workspace’s numbers and puts a published voice agent on it. For a list of people, use batch calling.

This places a real, billable call to a real person. There is no test mode; the dashboard’s test-call button on a phone number calls this same endpoint. The request returns when the call has been placed, not when it is answered.

curl -sS https://api.talqing.com/v1/calls/outbound \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_phone_number_id": "8b41d0e6-2c77-4a19-b3f5-91ad6e40c8b2",
    "to": "+919876543210",
    "agent_id": "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    "userdata": { "name": "Priya", "policy_number": "NW-40182" }
  }'

const call = await talqing.calls.outbound({
  outboundCallRequest: {
    from_phone_number_id: "8b41d0e6-2c77-4a19-b3f5-91ad6e40c8b2",
    to: "+919876543210",
    agent_id: "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    userdata: { name: "Priya", policy_number: "NW-40182" },
  },
});
console.log(call.session_id, call.warnings);

call = talqing.calls.outbound(
    from_phone_number_id="8b41d0e6-2c77-4a19-b3f5-91ad6e40c8b2",
    to="+919876543210",
    agent_id="9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    userdata={"name": "Priya", "policy_number": "NW-40182"},
)
print(call["session_id"], call["warnings"])

Request

uuid

required

The number to dial from. It must be active, have can_outbound on, and belong to a carrier account that is ready. Its E.164 is the caller ID the person sees; caller ID cannot be set per call. The call is hosted in the number’s region.

string

required

The number to dial, in any format. Normalized as described below.

uuid

A published voice agent. A video or text agent is refused.

object

What the call starts knowing about the person, read as {{userdata.field}}. Merged onto their contact record, so it is there on their next call. Keys starting with _talqing are reserved. See userdata.

object

String values for the agent’s declared variables, read as {{vars.name}}. They last for this call only and are never written to a contact record. A required variable with no default must be supplied. See variables.

agent_version (including "draft"), agent_override, an inline agent and agent_team work here as on every session-starting endpoint; see per-call configuration. The resolved agent is validated at request time, so a bad override is a 400, not a failed call.

How `to` is normalized

to is normalized to E.164 against the country of the number you dial from. A national-format number is read as national to that country. The result must be a valid, assignable number or the request is refused.

You send	From `+912248900123` (India)	From `+442079460000` (UK)
`+919876543210`	`+919876543210`	`+919876543210`
`00919876543210`	`+919876543210`	`+919876543210`
`07911123456`	`+917911123456`	`+447911123456`
`09876543210`	`+919876543210`	Refused

Send full international format when in doubt.

Response

{
  "session_id": "5c3ba6d2-08a7-4c1e-b6f0-7e1a94c3d2f8",
  "warnings": []
}

GET /v1/calls/{session_id} answers on this id immediately and carries status, transcript, latency and cost (null until the call is priced); see calls. warnings lists what resolving the agent plan flagged but did not refuse (for example an unreachable team member). It is not stored anywhere — log it from this response. The session.queued webhook fires as the call is placed and session.completed after it ends and its recording, analysis and billing have landed; see webhooks.

Credit

A workspace with no credit gets a 402 and nothing is written or dialled. See pricing and credits.

Voicemail is only detected if the agent has voicemail_detection on. Off (the default), a call that reaches voicemail is answered, billed, and recorded as a normal completion with the agent talking to nobody.

Limits on a call

Limit	Value	Behaviour
Ring time	60 seconds	Platform-wide; not settable per call.
Call duration	`max_duration_seconds`, default 30 minutes, at most 3 hours	The call is ended at the cap; see silence and call length.
No audio on the line	120 seconds	The leg is dropped. A caller parked on silent hold this long disappears.

Errors

Status	Message	Cause
`400`	`this number is not enabled for outbound`	`can_outbound` is false.
`400`	`phone number must be active (provisioned) for outbound calls`	The number is not `active`.
`400`	`telephony account is not ready for outbound; provision it first`	The carrier account is not `ready`.
`400`	`to: '…' is not a valid number to dial from …`	`to` did not normalize to a valid number.
`400`	`'<name>' is required and has no default`	A required variable is missing from `vars`.
`400`	`this endpoint runs voice agents; …`	The agent is not on the `voice` channel.
`402`	Out of credits	Top up and retry.
`404`	`phone number not found` / `agent not found`	Wrong id.
`502`	`failed to dispatch outbound call: …`	The call could not be started; the session ends as `sip_dispatch_failed`.

Batch calling

The same call, to a list, on a schedule.

Close reasons

Every way a call can end.

Get started

Build

Guides

Request

How `to` is normalized

Response

Credit

Limits on a call

Errors

Next

Batch calling

Close reasons

​Request

​How to is normalized

​Response

​Credit

​Limits on a call

​Errors

​Next

Batch calling

Close reasons

Request

How `to` is normalized

Response

Credit

Limits on a call

Errors

Next