Start an outbound conversation

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": "<string>",
  "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: '<string>',
    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": "<string>",
    "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": "successful",
  "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": [
      {
        "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

Required string length: 8 - 200

toNumber

string

required

International telephone number in E.164 form.

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

Example:

"+573001234567"

channelId

string

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"

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

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,

telegram,

slack,

email,

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

Structured business outcome assigned to a Conversation.

Available options:

successful,

unsuccessful,

follow_up_needed,

no_answer

Example:

"successful"

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

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"

⌘I

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": "<string>",
  "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: '<string>',
    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": "<string>",
    "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": "successful",
  "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": [
      {
        "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