Start an outbound conversation

Starts one outbound voice Conversation under conversations:write. Callers do not provide channelId: Agents validates the organization and Agent, prefers that Agent’s active outbound voice channel, and otherwise uses the organization’s enabled platform-managed global outbound line. Provider routing and persistence stay inside Agents. Reuse the same idempotencyKey after an uncertain response to recover the original Conversation instead of starting another call.

POST

conversations

curl --request POST \
  --url https://api.getarbol.com/v1/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "idempotencyKey": "call-20260830-contact-42",
  "toNumber": "+573001234567"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agentId: 'agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31',
    idempotencyKey: 'call-20260830-contact-42',
    toNumber: '+573001234567'
  })
};

fetch('https://api.getarbol.com/v1/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.getarbol.com/v1/conversations"

payload = {
    "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
    "idempotencyKey": "call-20260830-contact-42",
    "toNumber": "+573001234567"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "channelKind": "voice",
  "closeReason": "completed",
  "contactId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "createdAt": "2026-08-29T14:30:00Z",
  "direction": "inbound",
  "durationSeconds": 4503599627370495,
  "endedAt": "2026-08-29T14:30:00Z",
  "id": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "language": "<string>",
  "lastMessageAt": "2026-08-29T14:30:00Z",
  "messageCount": 4503599627370495,
  "originKind": "manual",
  "outcome": "success",
  "sentiment": "neutral",
  "startedAt": "2026-08-29T14:30:00Z",
  "status": "open",
  "subjectContactId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "summary": "<string>",
  "title": "<string>",
  "updatedAt": "2026-08-29T14:30:00Z"
}

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "<string>",
  "data": {
    "issues": [
      {
        "code": "custom",
        "message": "<string>",
        "path": [
          "<string>"
        ]
      }
    ],
    "truncated": true
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "<string>",
  "data": {
    "missingPermissions": [
      "agents:read"
    ]
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "CONFLICT",
  "status": 409,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "UNPROCESSABLE_CONTENT",
  "status": 422,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "TOO_MANY_REQUESTS",
  "status": 429,
  "message": "<string>",
  "data": {
    "retryAfterSeconds": 123
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "SERVICE_UNAVAILABLE",
  "status": 503,
  "message": "<string>",
  "data": "<unknown>"
}

Authorizations

Authorization

string

header

required

Organization-scoped Auth0 user access token issued to an approved first-party client or exchanged by a trusted OBO resource server.

Body

application/json

agentId

string

required

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

idempotencyKey

string

required

Caller-generated key that identifies this outbound attempt. Reuse it only when recovering the same uncertain request.

Required string length: 8 - 200

Example:

"call-20260830-contact-42"

toNumber

string

required

Destination number. The source line is fromChannelId when given, otherwise selected by Agents.

Pattern: ^\+[1-9]\d{7,14}$

Example:

"+573001234567"

contactId

string | null

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

dynamicVariables

object

Show child attributes

firstMessage

string

Required string length: 1 - 2000

fromChannelId

string

Connected voice channel to call from. Absent: the Agent's own outbound channel, then the organization's platform-managed line.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

prompt

string

Replaces the Agent's system prompt for this call only. The Agent's stored configuration is untouched.

Required string length: 1 - 20000

subjectContactId

string | null

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

title

string | null

Maximum string length: 500

Response

Tenant-scoped Conversation metadata; transcripts and media require separate authorized expansions.

agentId

string | null

required

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

channelKind

enum<string>

required

Conversation transport family.

Available options:

voice,

whatsapp,

web

Example:

"voice"

closeReason

enum<string> | null

required

Reason recorded when a Conversation enters its closed state.

Available options:

completed,

inactivity,

handoff,

provider_migration,

error,

manual

Example:

"completed"

contactId

string | null

required

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

createdAt

string<date-time>

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

direction

enum<string>

required

Direction of a Conversation relative to the organization.

Available options:

inbound,

outbound

Example:

"inbound"

durationSeconds

integer | null

required

Required range: 0 <= x <= 9007199254740991

endedAt

string<date-time> | null

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

string

required

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

language

string | null

required

Maximum string length: 35

lastMessageAt

string<date-time> | null

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

messageCount

integer

required

Required range: 0 <= x <= 9007199254740991

originKind

enum<string>

required

Source that created the Conversation record.

Available options:

inbound,

manual,

automation,

import,

test

Example:

"manual"

outcome

enum<string> | null

required

Success evaluation aggregated from the applicable Conversation assessment criteria.

Available options:

success,

failure,

unknown

Example:

"success"

sentiment

enum<string> | null

required

Coarse sentiment assigned to a Conversation.

Available options:

positive,

neutral,

negative

Example:

"neutral"

startedAt

string<date-time>

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

status

enum<string>

required

Durable lifecycle state of a Conversation.

Available options:

open,

closed

Example:

"open"

subjectContactId

string | null

required

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

summary

string | null

required

Maximum string length: 8000

title

string | null

required

Display title. Non-test messaging conversations receive an early channel fallback, refined from the first substantive inbound; closure analysis may enrich it. Explicit human titles are preserved.

Maximum string length: 500

updatedAt

string<date-time>

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

Start an outbound conversation

curl --request POST \
  --url https://api.getarbol.com/v1/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "idempotencyKey": "call-20260830-contact-42",
  "toNumber": "+573001234567"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agentId: 'agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31',
    idempotencyKey: 'call-20260830-contact-42',
    toNumber: '+573001234567'
  })
};

fetch('https://api.getarbol.com/v1/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.getarbol.com/v1/conversations"

payload = {
    "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
    "idempotencyKey": "call-20260830-contact-42",
    "toNumber": "+573001234567"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "channelKind": "voice",
  "closeReason": "completed",
  "contactId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "createdAt": "2026-08-29T14:30:00Z",
  "direction": "inbound",
  "durationSeconds": 4503599627370495,
  "endedAt": "2026-08-29T14:30:00Z",
  "id": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "language": "<string>",
  "lastMessageAt": "2026-08-29T14:30:00Z",
  "messageCount": 4503599627370495,
  "originKind": "manual",
  "outcome": "success",
  "sentiment": "neutral",
  "startedAt": "2026-08-29T14:30:00Z",
  "status": "open",
  "subjectContactId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "summary": "<string>",
  "title": "<string>",
  "updatedAt": "2026-08-29T14:30:00Z"
}

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "<string>",
  "data": {
    "issues": [
      {
        "code": "custom",
        "message": "<string>",
        "path": [
          "<string>"
        ]
      }
    ],
    "truncated": true
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "<string>",
  "data": {
    "missingPermissions": [
      "agents:read"
    ]
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "CONFLICT",
  "status": 409,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "UNPROCESSABLE_CONTENT",
  "status": 422,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "TOO_MANY_REQUESTS",
  "status": 429,
  "message": "<string>",
  "data": {
    "retryAfterSeconds": 123
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "SERVICE_UNAVAILABLE",
  "status": 503,
  "message": "<string>",
  "data": "<unknown>"
}

Overview

Endpoints

Start an outbound conversation

Authorizations

Body

Response