agentlyleads docs
Chat API

API Reference

The reference below covers every endpoint in the Chat API. Code examples are generated automatically; the live playground is disabled to prevent accidental writes to production from the docs site.

GET/api/v1/chats

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Query Parameters

status?string

Which queue to list. Omit for everything not in spam or trash.

Value in

  • "waiting"
  • "open"
  • "closed"
  • "spam"
  • "trash"
  • "all"
handler?string

Who is answering the visitor. Case-insensitive.

Value in

  • "AI"
  • "HUMAN"
  • "WAITING"
assigneeId?string

Only conversations assigned to this workspace user. Pass none for unassigned ones.

siteId?string

Only conversations on this chat site.

since?string

Only conversations with a message at or after this ISO 8601 datetime. updatedSince is accepted as an alias.

Formatdate-time
limit?integer

Page size.

Range1 <= value <= 1000
Default100
cursor?string

The nextCursor value from the previous page.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/chats"
{  "chats": [    {      "id": "cmq5chat0alk34567890",      "threadKey": "chat:cmq5chat0alk34567890",      "status": "OPEN",      "spam": true,      "trashed": true,      "handler": "AI",      "handlerUser": {        "id": "string",        "name": "string"      },      "waitingReason": "TEAM_MODE",      "waitingSince": "2019-08-24T14:15:22Z",      "waitingMins": 0,      "live": true,      "hot": true,      "site": {        "id": "string",        "name": "string"      },      "visitor": {        "name": "string",        "email": "string",        "phone": "string",        "pageUrl": "string",        "referrer": "string",        "locale": "string",        "timezone": "string",        "blocked": true,        "blockedUntil": "2019-08-24T14:15:22Z"      },      "contact": {        "id": "string",        "name": "string",        "email": "string"      },      "lead": {        "id": "string",        "name": "string",        "email": "string"      },      "assignee": {        "id": "string",        "name": "string"      },      "tags": [        {          "id": "string",          "name": "string",          "color": "string"        }      ],      "subject": "string",      "snippet": "string",      "messageCount": 0,      "lastMessageAt": "2019-08-24T14:15:22Z",      "lastVisitorAt": "2019-08-24T14:15:22Z",      "lastAgentAt": "2019-08-24T14:15:22Z",      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "nextCursor": "string"}
{  "error": "status must be one of: waiting, open, closed, spam, trash, all."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: read:chat."}
{  "error": "Rate limit exceeded."}
GET/api/v1/chats/{id}

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The chat conversation ID.

Query Parameters

after?string

Only return messages after this message id.

limit?integer

Maximum number of messages to return.

Range1 <= value <= 500
Default500

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/chats/string"
{  "chat": {    "id": "cmq5chat0alk34567890",    "threadKey": "chat:cmq5chat0alk34567890",    "status": "OPEN",    "spam": true,    "trashed": true,    "handler": "AI",    "handlerUser": {      "id": "string",      "name": "string"    },    "waitingReason": "TEAM_MODE",    "waitingSince": "2019-08-24T14:15:22Z",    "waitingMins": 0,    "live": true,    "hot": true,    "site": {      "id": "string",      "name": "string"    },    "visitor": {      "name": "string",      "email": "string",      "phone": "string",      "pageUrl": "string",      "referrer": "string",      "locale": "string",      "timezone": "string",      "blocked": true,      "blockedUntil": "2019-08-24T14:15:22Z"    },    "contact": {      "id": "string",      "name": "string",      "email": "string"    },    "lead": {      "id": "string",      "name": "string",      "email": "string"    },    "assignee": {      "id": "string",      "name": "string"    },    "tags": [      {        "id": "string",        "name": "string",        "color": "string"      }    ],    "subject": "string",    "snippet": "string",    "messageCount": 0,    "lastMessageAt": "2019-08-24T14:15:22Z",    "lastVisitorAt": "2019-08-24T14:15:22Z",    "lastAgentAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  },  "messages": [    {      "id": "string",      "role": "VISITOR",      "userId": "string",      "userName": "string",      "body": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "messagesNextCursor": "string"}
{  "error": "limit must be an integer between 1 and 500."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: read:chat."}
{  "error": "Conversation not found."}
POST/api/v1/chats/{id}/reply

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The chat conversation ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/chats/string/reply" \  -H "Content-Type: application/json" \  -d '{    "body": "Yes, we ship to Canada. Most orders arrive in 3 to 5 business days."  }'
{  "message": {    "id": "string",    "role": "VISITOR",    "userId": "string",    "userName": "string",    "body": "string",    "createdAt": "2019-08-24T14:15:22Z"  },  "chat": {    "id": "cmq5chat0alk34567890",    "threadKey": "chat:cmq5chat0alk34567890",    "status": "OPEN",    "spam": true,    "trashed": true,    "handler": "AI",    "handlerUser": {      "id": "string",      "name": "string"    },    "waitingReason": "TEAM_MODE",    "waitingSince": "2019-08-24T14:15:22Z",    "waitingMins": 0,    "live": true,    "hot": true,    "site": {      "id": "string",      "name": "string"    },    "visitor": {      "name": "string",      "email": "string",      "phone": "string",      "pageUrl": "string",      "referrer": "string",      "locale": "string",      "timezone": "string",      "blocked": true,      "blockedUntil": "2019-08-24T14:15:22Z"    },    "contact": {      "id": "string",      "name": "string",      "email": "string"    },    "lead": {      "id": "string",      "name": "string",      "email": "string"    },    "assignee": {      "id": "string",      "name": "string"    },    "tags": [      {        "id": "string",        "name": "string",        "color": "string"      }    ],    "subject": "string",    "snippet": "string",    "messageCount": 0,    "lastMessageAt": "2019-08-24T14:15:22Z",    "lastVisitorAt": "2019-08-24T14:15:22Z",    "lastAgentAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  }}
{  "error": "asUserId (or asUserEmail) is required to reply: name the workspace member the visitor will see."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: write:chat."}
{  "error": "Conversation not found."}
POST/api/v1/chats/{id}/take-over

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The chat conversation ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The workspace member the action is taken as. Give one of the two.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/chats/string/take-over" \  -H "Content-Type: application/json" \  -d '{    "asUserId": "cmq1user0alk34567890"  }'
{  "chat": {    "id": "cmq5chat0alk34567890",    "threadKey": "chat:cmq5chat0alk34567890",    "status": "OPEN",    "spam": true,    "trashed": true,    "handler": "AI",    "handlerUser": {      "id": "string",      "name": "string"    },    "waitingReason": "TEAM_MODE",    "waitingSince": "2019-08-24T14:15:22Z",    "waitingMins": 0,    "live": true,    "hot": true,    "site": {      "id": "string",      "name": "string"    },    "visitor": {      "name": "string",      "email": "string",      "phone": "string",      "pageUrl": "string",      "referrer": "string",      "locale": "string",      "timezone": "string",      "blocked": true,      "blockedUntil": "2019-08-24T14:15:22Z"    },    "contact": {      "id": "string",      "name": "string",      "email": "string"    },    "lead": {      "id": "string",      "name": "string",      "email": "string"    },    "assignee": {      "id": "string",      "name": "string"    },    "tags": [      {        "id": "string",        "name": "string",        "color": "string"      }    ],    "subject": "string",    "snippet": "string",    "messageCount": 0,    "lastMessageAt": "2019-08-24T14:15:22Z",    "lastVisitorAt": "2019-08-24T14:15:22Z",    "lastAgentAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  }}
{  "error": "asUserId (or asUserEmail) is required to take over a chat: name the workspace member the visitor will see."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: write:chat."}
{  "error": "Conversation not found."}
POST/api/v1/chats/{id}/hand-back

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The chat conversation ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The workspace member the action is taken as. Give one of the two.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/chats/string/hand-back" \  -H "Content-Type: application/json" \  -d '{}'
{  "chat": {    "id": "cmq5chat0alk34567890",    "threadKey": "chat:cmq5chat0alk34567890",    "status": "OPEN",    "spam": true,    "trashed": true,    "handler": "AI",    "handlerUser": {      "id": "string",      "name": "string"    },    "waitingReason": "TEAM_MODE",    "waitingSince": "2019-08-24T14:15:22Z",    "waitingMins": 0,    "live": true,    "hot": true,    "site": {      "id": "string",      "name": "string"    },    "visitor": {      "name": "string",      "email": "string",      "phone": "string",      "pageUrl": "string",      "referrer": "string",      "locale": "string",      "timezone": "string",      "blocked": true,      "blockedUntil": "2019-08-24T14:15:22Z"    },    "contact": {      "id": "string",      "name": "string",      "email": "string"    },    "lead": {      "id": "string",      "name": "string",      "email": "string"    },    "assignee": {      "id": "string",      "name": "string"    },    "tags": [      {        "id": "string",        "name": "string",        "color": "string"      }    ],    "subject": "string",    "snippet": "string",    "messageCount": 0,    "lastMessageAt": "2019-08-24T14:15:22Z",    "lastVisitorAt": "2019-08-24T14:15:22Z",    "lastAgentAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  }}
{  "error": "Only the person handling this chat can hand it back."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: write:chat."}
{  "error": "Conversation not found."}
POST/api/v1/chats/{id}/close

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The chat conversation ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The workspace member the action is taken as. Give one of the two.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/chats/string/close" \  -H "Content-Type: application/json" \  -d '{}'
{  "chat": {    "id": "cmq5chat0alk34567890",    "threadKey": "chat:cmq5chat0alk34567890",    "status": "OPEN",    "spam": true,    "trashed": true,    "handler": "AI",    "handlerUser": {      "id": "string",      "name": "string"    },    "waitingReason": "TEAM_MODE",    "waitingSince": "2019-08-24T14:15:22Z",    "waitingMins": 0,    "live": true,    "hot": true,    "site": {      "id": "string",      "name": "string"    },    "visitor": {      "name": "string",      "email": "string",      "phone": "string",      "pageUrl": "string",      "referrer": "string",      "locale": "string",      "timezone": "string",      "blocked": true,      "blockedUntil": "2019-08-24T14:15:22Z"    },    "contact": {      "id": "string",      "name": "string",      "email": "string"    },    "lead": {      "id": "string",      "name": "string",      "email": "string"    },    "assignee": {      "id": "string",      "name": "string"    },    "tags": [      {        "id": "string",        "name": "string",        "color": "string"      }    ],    "subject": "string",    "snippet": "string",    "messageCount": 0,    "lastMessageAt": "2019-08-24T14:15:22Z",    "lastVisitorAt": "2019-08-24T14:15:22Z",    "lastAgentAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  }}
{  "error": "asUserId \"cmq1user9alk34567890\" is not a member of this workspace."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: write:chat."}
{  "error": "Conversation not found."}
POST/api/v1/chats/{id}/reopen

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The chat conversation ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The workspace member the action is taken as. Give one of the two.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/chats/string/reopen" \  -H "Content-Type: application/json" \  -d '{}'
{  "chat": {    "id": "cmq5chat0alk34567890",    "threadKey": "chat:cmq5chat0alk34567890",    "status": "OPEN",    "spam": true,    "trashed": true,    "handler": "AI",    "handlerUser": {      "id": "string",      "name": "string"    },    "waitingReason": "TEAM_MODE",    "waitingSince": "2019-08-24T14:15:22Z",    "waitingMins": 0,    "live": true,    "hot": true,    "site": {      "id": "string",      "name": "string"    },    "visitor": {      "name": "string",      "email": "string",      "phone": "string",      "pageUrl": "string",      "referrer": "string",      "locale": "string",      "timezone": "string",      "blocked": true,      "blockedUntil": "2019-08-24T14:15:22Z"    },    "contact": {      "id": "string",      "name": "string",      "email": "string"    },    "lead": {      "id": "string",      "name": "string",      "email": "string"    },    "assignee": {      "id": "string",      "name": "string"    },    "tags": [      {        "id": "string",        "name": "string",        "color": "string"      }    ],    "subject": "string",    "snippet": "string",    "messageCount": 0,    "lastMessageAt": "2019-08-24T14:15:22Z",    "lastVisitorAt": "2019-08-24T14:15:22Z",    "lastAgentAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  }}
{  "error": "asUserId \"cmq1user9alk34567890\" is not a member of this workspace."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: write:chat."}
{  "error": "Conversation not found."}
POST/api/v1/chats/{id}/assign

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The chat conversation ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/chats/string/assign" \  -H "Content-Type: application/json" \  -d '{    "assigneeId": "cmq1user0alk34567890"  }'
{  "chat": {    "id": "cmq5chat0alk34567890",    "threadKey": "chat:cmq5chat0alk34567890",    "status": "OPEN",    "spam": true,    "trashed": true,    "handler": "AI",    "handlerUser": {      "id": "string",      "name": "string"    },    "waitingReason": "TEAM_MODE",    "waitingSince": "2019-08-24T14:15:22Z",    "waitingMins": 0,    "live": true,    "hot": true,    "site": {      "id": "string",      "name": "string"    },    "visitor": {      "name": "string",      "email": "string",      "phone": "string",      "pageUrl": "string",      "referrer": "string",      "locale": "string",      "timezone": "string",      "blocked": true,      "blockedUntil": "2019-08-24T14:15:22Z"    },    "contact": {      "id": "string",      "name": "string",      "email": "string"    },    "lead": {      "id": "string",      "name": "string",      "email": "string"    },    "assignee": {      "id": "string",      "name": "string"    },    "tags": [      {        "id": "string",        "name": "string",        "color": "string"      }    ],    "subject": "string",    "snippet": "string",    "messageCount": 0,    "lastMessageAt": "2019-08-24T14:15:22Z",    "lastVisitorAt": "2019-08-24T14:15:22Z",    "lastAgentAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  }}
{  "error": "assigneeId \"cmq1user9alk34567890\" is not an active member of this workspace."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: write:chat."}
{  "error": "Conversation not found."}
POST/api/v1/chats/{id}/tags

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The chat conversation ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Give tagId or name.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/chats/string/tags" \  -H "Content-Type: application/json" \  -d '{    "name": "Pricing"  }'
{  "chat": {    "id": "cmq5chat0alk34567890",    "threadKey": "chat:cmq5chat0alk34567890",    "status": "OPEN",    "spam": true,    "trashed": true,    "handler": "AI",    "handlerUser": {      "id": "string",      "name": "string"    },    "waitingReason": "TEAM_MODE",    "waitingSince": "2019-08-24T14:15:22Z",    "waitingMins": 0,    "live": true,    "hot": true,    "site": {      "id": "string",      "name": "string"    },    "visitor": {      "name": "string",      "email": "string",      "phone": "string",      "pageUrl": "string",      "referrer": "string",      "locale": "string",      "timezone": "string",      "blocked": true,      "blockedUntil": "2019-08-24T14:15:22Z"    },    "contact": {      "id": "string",      "name": "string",      "email": "string"    },    "lead": {      "id": "string",      "name": "string",      "email": "string"    },    "assignee": {      "id": "string",      "name": "string"    },    "tags": [      {        "id": "string",        "name": "string",        "color": "string"      }    ],    "subject": "string",    "snippet": "string",    "messageCount": 0,    "lastMessageAt": "2019-08-24T14:15:22Z",    "lastVisitorAt": "2019-08-24T14:15:22Z",    "lastAgentAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  }}
{  "error": "Pass tagId (an existing tag) or name."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: write:chat."}
{  "error": "Tag not found."}
DELETE/api/v1/chats/{id}/tags

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The chat conversation ID.

Query Parameters

tagId?string

The tag to remove.

name?string

The tag to remove, by name, instead of tagId.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/v1/chats/string/tags"
{  "chat": {    "id": "cmq5chat0alk34567890",    "threadKey": "chat:cmq5chat0alk34567890",    "status": "OPEN",    "spam": true,    "trashed": true,    "handler": "AI",    "handlerUser": {      "id": "string",      "name": "string"    },    "waitingReason": "TEAM_MODE",    "waitingSince": "2019-08-24T14:15:22Z",    "waitingMins": 0,    "live": true,    "hot": true,    "site": {      "id": "string",      "name": "string"    },    "visitor": {      "name": "string",      "email": "string",      "phone": "string",      "pageUrl": "string",      "referrer": "string",      "locale": "string",      "timezone": "string",      "blocked": true,      "blockedUntil": "2019-08-24T14:15:22Z"    },    "contact": {      "id": "string",      "name": "string",      "email": "string"    },    "lead": {      "id": "string",      "name": "string",      "email": "string"    },    "assignee": {      "id": "string",      "name": "string"    },    "tags": [      {        "id": "string",        "name": "string",        "color": "string"      }    ],    "subject": "string",    "snippet": "string",    "messageCount": 0,    "lastMessageAt": "2019-08-24T14:15:22Z",    "lastVisitorAt": "2019-08-24T14:15:22Z",    "lastAgentAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  }}
{  "error": "Pass tagId (an existing tag) or name."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: write:chat."}
{  "error": "No tag named \"Pricing\" in this workspace."}
POST/api/v1/chats/{id}/spam

Authorization

BearerAuth
AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The chat conversation ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/chats/string/spam" \  -H "Content-Type: application/json" \  -d '{    "spam": true  }'
{  "chat": {    "id": "cmq5chat0alk34567890",    "threadKey": "chat:cmq5chat0alk34567890",    "status": "OPEN",    "spam": true,    "trashed": true,    "handler": "AI",    "handlerUser": {      "id": "string",      "name": "string"    },    "waitingReason": "TEAM_MODE",    "waitingSince": "2019-08-24T14:15:22Z",    "waitingMins": 0,    "live": true,    "hot": true,    "site": {      "id": "string",      "name": "string"    },    "visitor": {      "name": "string",      "email": "string",      "phone": "string",      "pageUrl": "string",      "referrer": "string",      "locale": "string",      "timezone": "string",      "blocked": true,      "blockedUntil": "2019-08-24T14:15:22Z"    },    "contact": {      "id": "string",      "name": "string",      "email": "string"    },    "lead": {      "id": "string",      "name": "string",      "email": "string"    },    "assignee": {      "id": "string",      "name": "string"    },    "tags": [      {        "id": "string",        "name": "string",        "color": "string"      }    ],    "subject": "string",    "snippet": "string",    "messageCount": 0,    "lastMessageAt": "2019-08-24T14:15:22Z",    "lastVisitorAt": "2019-08-24T14:15:22Z",    "lastAgentAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  }}
{  "error": "spam is required: true to mark as spam and block the visitor, false to undo."}
{  "error": "Invalid or missing API key."}
{  "error": "API key missing required scope: write:chat."}
{  "error": "Conversation not found."}

Errors

Error codes and response shapes returned by the agentlyleads Chat API.

The Campaign object

Fields and types for the agentlyleads Campaign object returned by the Campaigns API.