An AI agent calls a number

curl --request POST \
  --url https://{host}/api/v1/calls/ai \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "to": "+61412345678",
  "callback_url": "<string>",
  "caller_id": "+61298765432",
  "organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "variables": {
    "interest": "teeth whitening",
    "name": "Sam"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    profile_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    to: '+61412345678',
    callback_url: '<string>',
    caller_id: '+61298765432',
    organisation_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    reference: '<string>',
    variables: {interest: 'teeth whitening', name: 'Sam'}
  })
};

fetch('https://{host}/api/v1/calls/ai', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/api/v1/calls/ai"

payload = {
    "profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "to": "+61412345678",
    "callback_url": "<string>",
    "caller_id": "+61298765432",
    "organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reference": "<string>",
    "variables": {
        "interest": "teeth whitening",
        "name": "Sam"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "plan": {
    "agent": "<string>",
    "caller_id": "<string>",
    "max_seconds": 123,
    "to_e164": "<string>",
    "trunk": "<string>"
  },
  "reference": "<string>",
  "request_id": "<string>",
  "status": "<string>"
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>"
  }
}

Live

An AI agent calls a number

The profile’s virtual agent rings to from caller_id (one of your numbers; optional when you have exactly one) and talks to whoever answers, with variables in its brief as what it knows about this call. Answers 202 at once: the dial happens in the background, and how it went is posted to callback_url (call.started, call.answered, conversation.completed with the summary, call.ended; call.failed with the reason if nobody answered) and kept on the request (GET /call-requests/). Refused 422 with the reason: the number is one of your own, no route reaches it, billing refuses it, or no agent uses the profile. Rate limited with click-to-call (60 a minute per key). Requires calls:originate.

An AI agent calls a number

curl --request POST \
  --url https://{host}/api/v1/calls/ai \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "to": "+61412345678",
  "callback_url": "<string>",
  "caller_id": "+61298765432",
  "organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "variables": {
    "interest": "teeth whitening",
    "name": "Sam"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    profile_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    to: '+61412345678',
    callback_url: '<string>',
    caller_id: '+61298765432',
    organisation_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    reference: '<string>',
    variables: {interest: 'teeth whitening', name: 'Sam'}
  })
};

fetch('https://{host}/api/v1/calls/ai', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/api/v1/calls/ai"

payload = {
    "profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "to": "+61412345678",
    "callback_url": "<string>",
    "caller_id": "+61298765432",
    "organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reference": "<string>",
    "variables": {
        "interest": "teeth whitening",
        "name": "Sam"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "plan": {
    "agent": "<string>",
    "caller_id": "<string>",
    "max_seconds": 123,
    "to_e164": "<string>",
    "trunk": "<string>"
  },
  "reference": "<string>",
  "request_id": "<string>",
  "status": "<string>"
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Every request sends Authorization: Bearer <token>. The token is either a panel session (a JWT from /auth/login, 12 hours) or an API key ft_<id>_<secret>. An API key is accepted only from an address on its IP allowlist (403 ip_not_allowed otherwise; 403 ip_allowlist_required for an old key that has none), is limited to its rate per minute (429 rate_limited with Retry-After; X-RateLimit-Limit/Remaining/Reset on every response), and at most 60 call placements a minute.

Headers

Idempotency-Key

string

Any string up to 255 characters. A retry with the same key and the same body gets the first answer again (with Idempotent-Replayed: true) instead of doing it twice; the same key with a different body is 409 idempotency_mismatch; while the first is still running, 409 idempotency_in_progress. Kept 24 hours.

Maximum string length: 255

Query Parameters

dry_run

boolean

true: check everything, place nothing, and return the plan.

Body

application/json

profile_id

string<uuid>

required

to

string

required

Example:

"+61412345678"

callback_url

string

caller_id

string

Example:

"+61298765432"

organisation_id

string<uuid>

reference

string

Maximum string length: 128

variables

object

Show child attributes

Example:

{
  "interest": "teeth whitening",
  "name": "Sam"
}

Response

A dry run's plan