Bots API

A bot matches an inbound message and runs a node graph in reply. Five endpoints cover the full lifecycle. The same flows can be built in the dashboard, see Bots and auto-replies for what the nodes do.

Enums

trigger

KEYWORD, ANY_MESSAGE, BUTTON_REPLY, LIST_REPLY, OPTIN. Defaults to KEYWORD.

triggerMatchType

EXACT, CONTAINS, STARTS_WITH. Defaults to CONTAINS, which matches a keyword anywhere in the message.

Both are validated as enums, so a lowercase value or a near-miss like ANY fails with a 400 rather than being ignored.

Listing bots

Lists every bot on the account, newest first.

Parameters: none.

[
  {
    "id": "clx8f2a0b0002abcd9012mnop",
    "name": "Order Support Bot",
    "description": null,
    "trigger": "KEYWORD",
    "triggerKeywords": ["order", "track"],
    "isActive": true,
    "totalExecutions": 42,
    "lastExecutedAt": "2026-08-05T09:12:00.000Z",
    "createdAt": "2026-07-10T00:00:00.000Z",
    "phoneNumber": { "phoneNumberId": "1030974986765331", "displayPhoneNumber": "+15556052643" }
  }
]

Errors: 401, 429.

One bot, with its graph

Returns one bot including its node graph.

Errors. 404 when no bot with that id belongs to this account:

{ "error": "Bot not found" }

Creating a bot

Creates a bot. Only the name is required; everything else has a default.

{
  "name": "Order Support Bot",
  "description": "Answers order questions",
  "phoneNumberId": "1030974986765331",
  "trigger": "KEYWORD",
  "triggerKeywords": ["order", "track"],
  "triggerMatchType": "CONTAINS",
  "isActive": true,
  "nodes": [],
  "edges": []
}

Response 201, the full bot, the same shape as GET /v1/bots/:botId.

{
  "id": "clx8f2a0b0002abcd9012mnop",
  "name": "Order Support Bot",
  "description": "Answers order questions",
  "trigger": "KEYWORD",
  "triggerKeywords": ["order", "track"],
  "triggerMatchType": "CONTAINS",
  "isActive": true,
  "nodes": [],
  "edges": [],
  "totalExecutions": 0,
  "lastExecutedAt": null,
  "createdAt": "2026-08-05T10:00:00.000Z"
}

Errors. 400 for a validation failure, with error as a Zod object, usually a name shorter than 2 characters, or an unrecognised trigger or triggerMatchType.

404 when phoneNumberId is not on this account:

{ "error": "Phone number not found" }

Updating a bot

Every field of the create schema is optional here. Only the fields you send are changed, and defaults are not re-applied, omitting isActive leaves it as it was rather than resetting it to true.

Body parameters: any subset of the POST /v1/bots table, all optional.

{
  "isActive": false,
  "triggerKeywords": ["order", "track", "delivery"]
}

Response 200, the full updated bot.

Errors. 400 for a validation failure (Zod object). 404 for Bot not found, or Phone number not found when the phoneNumberId you sent is not yours.

Deleting a bot

Deletes a bot permanently. There is no soft delete and no undo, deactivate instead if you only want it to stop running.

{ "success": true }

Errors. 404:

{ "error": "Bot not found" }

To pause a bot without losing its graph, PATCH it with { "isActive": false }.