Conversation Management

Lists and filters conversations

get

Required Permission: chatbots.conversations.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Query parameters

contactIdstringOptional

Filters by a contact ID.

channelIdstringOptional

Filters by a channel ID.

Responses

200Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get/v1/chatbots/{chatbotId}/conversations

GET /v1/chatbots/{chatbotId}/conversations HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "conversations": [
    {
      "id": "conv_abc123xyz",
      "contactId": "contact_def456",
      "archived": false,
      "channelId": "channel_ghi789",
      "channelType": "whatsapp",
      "chatbotId": "bot_jkl012",
      "idToken": "token_mno345",
      "language": "DE",
      "operatorId": "op_pqr678",
      "photoUrl": "https://example.com/photos/user123.jpg",
      "sessionCount": 3,
      "tags": [
        "vip",
        "sales"
      ],
      "unread": true,
      "variables": {
        "customer_name": "John",
        "order_id": "12345"
      },
      "lastBlock": {
        "id": "blk_abc123",
        "name": "Welcome Message"
      },
      "lastButton": {
        "id": "blk_abc123",
        "name": "Welcome Message"
      },
      "created": "2025-10-05T10:00:00Z",
      "updated": "2025-10-05T12:30:00Z",
      "providerId": "wa_123456789",
      "name": "John Doe",
      "lastMessage": {
        "text": "text",
        "file": {
          "name": "text",
          "url": "text",
          "type": "text",
          "mimeType": "text",
          "size": 1,
          "attachmentRef": "text",
          "caption": "text",
          "transcript": "text"
        },
        "buttons": {
          "buttons": [
            {
              "label": "text",
              "type": "text",
              "value": "text",
              "payload": "text"
            }
          ]
        },
        "selectedButton": {
          "label": "text",
          "value": "text",
          "payload": "text",
          "type": "text",
          "reference": "text"
        },
        "template": {
          "body": "text",
          "header": "text",
          "footer": "text"
        },
        "contact": {
          "addresses": [
            {
              "city": "text",
              "country": "text",
              "countryCode": "text",
              "street": "text",
              "type": "text",
              "zip": "text"
            }
          ],
          "emails": [
            {
              "email": "[e-mail]",
              "type": "text"
            }
          ],
          "name": {
            "firstName": "text",
            "formattedName": "text",
            "lastName": "text"
          },
          "org": {
            "company": "text",
            "title": "text"
          },
          "phones": [
            {
              "phone": "text",
              "type": "text",
              "waId": "text"
            }
          ]
        },
        "location": {
          "latitude": 1,
          "longitude": 1
        },
        "note": {
          "text": "text",
          "mentions": [
            "text"
          ]
        },
        "voiceHangup": {
          "reason": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        },
        "voiceTransfer": {
          "target": "text",
          "reason": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        },
        "agentHandover": {
          "reason": "text",
          "timeoutSeconds": 1,
          "agentId": "text",
          "groupId": "text",
          "assignmentMethod": "text"
        },
        "email": {
          "subject": "text",
          "body": "text",
          "from": "text",
          "to": [
            "text"
          ],
          "cc": [
            "text"
          ],
          "bcc": [
            "text"
          ],
          "attachmentIds": [
            "text"
          ],
          "references": [
            "text"
          ],
          "attachments": [
            {
              "id": "att_123",
              "name": "invoice.pdf",
              "created": "2024-01-01T00:00:00Z",
              "updated": "2024-01-01T00:00:00Z",
              "size": 102400,
              "contentType": "application/pdf",
              "selfLink": "bucketId-objectId/filename.filetype",
              "metadata": {
                "source": "email"
              }
            }
          ]
        },
        "transcription": {
          "text": "text",
          "language": "text",
          "audioRef": "text"
        },
        "textToSpeech": {
          "text": "text",
          "speech": "text"
        },
        "reaction": {
          "reactionToMid": "text",
          "action": "text",
          "reaction": "text",
          "emoji": "text"
        },
        "callSettings": {
          "userInputSpeechDetectionTimeout": 1,
          "dtmf": true,
          "bargeIn": true
        },
        "metaWhatsappTemplate": {
          "templateName": "order_shipped_notification",
          "language": "DE",
          "bodyText": "Your order {{1}} has been shipped.",
          "headerText": "text",
          "footerText": "text",
          "header": {
            "file": {
              "name": "header_image.png",
              "url": "https://storage.example.com/files/header.png",
              "type": "image",
              "mimeType": "image/png",
              "size": 51200,
              "attachmentRef": "att_header123"
            },
            "parameters": [
              "Order #12345"
            ]
          },
          "bodyParameters": [
            "#12345"
          ],
          "buttons": [
            {
              "label": "Track Order",
              "type": "URL",
              "url": "https://example.com/track/{{1}}",
              "value": "track_order"
            }
          ]
        },
        "operator": {
          "operatorId": "op_abc123xyz"
        },
        "delay": 1,
        "leadAiId": "text"
      },
      "snoozed": "2025-10-06T09:00:00Z",
      "lastUserAction": "2025-10-05T12:25:00Z",
      "mentions": [
        "user_123",
        "user_456"
      ],
      "mentionsRead": {
        "user_123": true,
        "user_456": false
      },
      "notes": {
        "notes": [
          "Customer prefers email contact",
          "VIP customer"
        ]
      },
      "lastSender": "user",
      "userInput": {
        "redirect": "flow_abc123",
        "isSensitive": false
      },
      "environment": "test",
      "metadata": {
        "source": "website",
        "campaign": "summer_sale"
      },
      "lastUserInput": "I need help with my order",
      "leadAiConversation": {
        "flowId": "flow_xyz789",
        "stepId": "step_abc123",
        "interactions": 5,
        "executionId": "exec_def456"
      },
      "team": {
        "teamId": "team_support_01"
      },
      "state": 0,
      "lastAssignedOperatorId": "op_xyz789",
      "lastSeen": "2025-10-05T12:30:00Z"
    }
  ],
  "error": "text"
}

Creates a new conversation

post

Required Permission: chatbots.conversations.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

Responses

201Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

post/v1/chatbots/{chatbotId}/conversations

POST /v1/chatbots/{chatbotId}/conversations HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2972

{
  "conversation": {
    "contactId": "contact_abc123",
    "channelId": "channel_def456",
    "channelType": "web",
    "name": "John Doe",
    "environment": "test",
    "providerId": "wa_123456789",
    "unread": true,
    "archived": false,
    "tags": {
      "tags": [
        "vip",
        "sales"
      ]
    },
    "notes": {
      "notes": [
        "Initial contact via web widget"
      ]
    },
    "lastMessage": {
      "text": "text",
      "file": {
        "name": "text",
        "url": "text",
        "type": "text",
        "mimeType": "text",
        "size": 1,
        "attachmentRef": "text",
        "caption": "text",
        "transcript": "text"
      },
      "buttons": {
        "buttons": [
          {
            "label": "text",
            "type": "text",
            "value": "text",
            "payload": "text"
          }
        ]
      },
      "selectedButton": {
        "label": "text",
        "value": "text",
        "payload": "text",
        "type": "text",
        "reference": "text"
      },
      "template": {
        "body": "text",
        "header": "text",
        "footer": "text"
      },
      "contact": {
        "addresses": [
          {
            "city": "text",
            "country": "text",
            "countryCode": "text",
            "street": "text",
            "type": "text",
            "zip": "text"
          }
        ],
        "emails": [
          {
            "email": "[e-mail]",
            "type": "text"
          }
        ],
        "name": {
          "firstName": "text",
          "formattedName": "text",
          "lastName": "text"
        },
        "org": {
          "company": "text",
          "title": "text"
        },
        "phones": [
          {
            "phone": "text",
            "type": "text",
            "waId": "text"
          }
        ]
      },
      "location": {
        "latitude": 1,
        "longitude": 1
      },
      "note": {
        "text": "text",
        "mentions": [
          "text"
        ]
      },
      "voiceHangup": {
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "voiceTransfer": {
        "target": "text",
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "agentHandover": {
        "reason": "text",
        "timeoutSeconds": 1,
        "agentId": "text",
        "groupId": "text",
        "assignmentMethod": "text"
      },
      "email": {
        "subject": "text",
        "body": "text",
        "from": "text",
        "to": [
          "text"
        ],
        "cc": [
          "text"
        ],
        "bcc": [
          "text"
        ],
        "attachmentIds": [
          "text"
        ],
        "references": [
          "text"
        ],
        "attachments": [
          {
            "id": "att_123",
            "name": "invoice.pdf",
            "created": "2024-01-01T00:00:00Z",
            "updated": "2024-01-01T00:00:00Z",
            "size": 102400,
            "contentType": "application/pdf",
            "selfLink": "bucketId-objectId/filename.filetype",
            "metadata": {
              "source": "email"
            }
          }
        ]
      },
      "transcription": {
        "text": "text",
        "language": "text",
        "audioRef": "text"
      },
      "textToSpeech": {
        "text": "text",
        "speech": "text"
      },
      "reaction": {
        "reactionToMid": "text",
        "action": "text",
        "reaction": "text",
        "emoji": "text"
      },
      "callSettings": {
        "userInputSpeechDetectionTimeout": 1,
        "dtmf": true,
        "bargeIn": true
      },
      "metaWhatsappTemplate": {
        "templateName": "order_shipped_notification",
        "language": "DE",
        "bodyText": "Your order {{1}} has been shipped.",
        "headerText": "text",
        "footerText": "text",
        "header": {
          "file": {
            "name": "header_image.png",
            "url": "https://storage.example.com/files/header.png",
            "type": "image",
            "mimeType": "image/png",
            "size": 51200,
            "attachmentRef": "att_header123"
          },
          "parameters": [
            "Order #12345"
          ]
        },
        "bodyParameters": [
          "#12345"
        ],
        "buttons": [
          {
            "label": "Track Order",
            "type": "URL",
            "url": "https://example.com/track/{{1}}",
            "value": "track_order"
          }
        ]
      },
      "operator": {
        "operatorId": "op_abc123xyz"
      },
      "delay": 1,
      "leadAiId": "text"
    },
    "operatorId": "op_xyz789",
    "snoozed": "2025-10-06T09:00:00Z",
    "lastUserAction": "2025-10-05T12:25:00Z",
    "lastSender": "user",
    "mentions": {
      "mentions": [
        "user_123",
        "user_456"
      ]
    },
    "metadata": {
      "source": "website",
      "campaign": "summer_sale"
    },
    "language": "DE",
    "lastAssignedOperatorId": "op_abc123",
    "lastSeen": "2025-10-05T12:30:00Z"
  }
}

{
  "conversation": {
    "id": "conv_abc123xyz",
    "contactId": "contact_def456",
    "archived": false,
    "channelId": "channel_ghi789",
    "channelType": "whatsapp",
    "chatbotId": "bot_jkl012",
    "idToken": "token_mno345",
    "language": "DE",
    "operatorId": "op_pqr678",
    "photoUrl": "https://example.com/photos/user123.jpg",
    "sessionCount": 3,
    "tags": [
      "vip",
      "sales"
    ],
    "unread": true,
    "variables": {
      "customer_name": "John",
      "order_id": "12345"
    },
    "lastBlock": {
      "id": "blk_abc123",
      "name": "Welcome Message"
    },
    "lastButton": {
      "id": "blk_abc123",
      "name": "Welcome Message"
    },
    "created": "2025-10-05T10:00:00Z",
    "updated": "2025-10-05T12:30:00Z",
    "providerId": "wa_123456789",
    "name": "John Doe",
    "lastMessage": {
      "text": "text",
      "file": {
        "name": "text",
        "url": "text",
        "type": "text",
        "mimeType": "text",
        "size": 1,
        "attachmentRef": "text",
        "caption": "text",
        "transcript": "text"
      },
      "buttons": {
        "buttons": [
          {
            "label": "text",
            "type": "text",
            "value": "text",
            "payload": "text"
          }
        ]
      },
      "selectedButton": {
        "label": "text",
        "value": "text",
        "payload": "text",
        "type": "text",
        "reference": "text"
      },
      "template": {
        "body": "text",
        "header": "text",
        "footer": "text"
      },
      "contact": {
        "addresses": [
          {
            "city": "text",
            "country": "text",
            "countryCode": "text",
            "street": "text",
            "type": "text",
            "zip": "text"
          }
        ],
        "emails": [
          {
            "email": "[e-mail]",
            "type": "text"
          }
        ],
        "name": {
          "firstName": "text",
          "formattedName": "text",
          "lastName": "text"
        },
        "org": {
          "company": "text",
          "title": "text"
        },
        "phones": [
          {
            "phone": "text",
            "type": "text",
            "waId": "text"
          }
        ]
      },
      "location": {
        "latitude": 1,
        "longitude": 1
      },
      "note": {
        "text": "text",
        "mentions": [
          "text"
        ]
      },
      "voiceHangup": {
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "voiceTransfer": {
        "target": "text",
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "agentHandover": {
        "reason": "text",
        "timeoutSeconds": 1,
        "agentId": "text",
        "groupId": "text",
        "assignmentMethod": "text"
      },
      "email": {
        "subject": "text",
        "body": "text",
        "from": "text",
        "to": [
          "text"
        ],
        "cc": [
          "text"
        ],
        "bcc": [
          "text"
        ],
        "attachmentIds": [
          "text"
        ],
        "references": [
          "text"
        ],
        "attachments": [
          {
            "id": "att_123",
            "name": "invoice.pdf",
            "created": "2024-01-01T00:00:00Z",
            "updated": "2024-01-01T00:00:00Z",
            "size": 102400,
            "contentType": "application/pdf",
            "selfLink": "bucketId-objectId/filename.filetype",
            "metadata": {
              "source": "email"
            }
          }
        ]
      },
      "transcription": {
        "text": "text",
        "language": "text",
        "audioRef": "text"
      },
      "textToSpeech": {
        "text": "text",
        "speech": "text"
      },
      "reaction": {
        "reactionToMid": "text",
        "action": "text",
        "reaction": "text",
        "emoji": "text"
      },
      "callSettings": {
        "userInputSpeechDetectionTimeout": 1,
        "dtmf": true,
        "bargeIn": true
      },
      "metaWhatsappTemplate": {
        "templateName": "order_shipped_notification",
        "language": "DE",
        "bodyText": "Your order {{1}} has been shipped.",
        "headerText": "text",
        "footerText": "text",
        "header": {
          "file": {
            "name": "header_image.png",
            "url": "https://storage.example.com/files/header.png",
            "type": "image",
            "mimeType": "image/png",
            "size": 51200,
            "attachmentRef": "att_header123"
          },
          "parameters": [
            "Order #12345"
          ]
        },
        "bodyParameters": [
          "#12345"
        ],
        "buttons": [
          {
            "label": "Track Order",
            "type": "URL",
            "url": "https://example.com/track/{{1}}",
            "value": "track_order"
          }
        ]
      },
      "operator": {
        "operatorId": "op_abc123xyz"
      },
      "delay": 1,
      "leadAiId": "text"
    },
    "snoozed": "2025-10-06T09:00:00Z",
    "lastUserAction": "2025-10-05T12:25:00Z",
    "mentions": [
      "user_123",
      "user_456"
    ],
    "mentionsRead": {
      "user_123": true,
      "user_456": false
    },
    "notes": {
      "notes": [
        "Customer prefers email contact",
        "VIP customer"
      ]
    },
    "lastSender": "user",
    "userInput": {
      "redirect": "flow_abc123",
      "isSensitive": false
    },
    "environment": "test",
    "metadata": {
      "source": "website",
      "campaign": "summer_sale"
    },
    "lastUserInput": "I need help with my order",
    "leadAiConversation": {
      "flowId": "flow_xyz789",
      "stepId": "step_abc123",
      "interactions": 5,
      "executionId": "exec_def456"
    },
    "team": {
      "teamId": "team_support_01"
    },
    "state": 0,
    "lastAssignedOperatorId": "op_xyz789",
    "lastSeen": "2025-10-05T12:30:00Z"
  },
  "error": "text"
}

Finds a conversation by external Id's

get

Required Permission: chatbots.conversations.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Query parameters

channelIdstringRequired

The Id of the channel.

providerIdstringRequired

The Id of the provider.

Responses

200Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get/v1/chatbots/{chatbotId}/conversations/find

GET /v1/chatbots/{chatbotId}/conversations/find?channelId=text&providerId=text HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "conversation": {
    "id": "conv_abc123xyz",
    "contactId": "contact_def456",
    "archived": false,
    "channelId": "channel_ghi789",
    "channelType": "whatsapp",
    "chatbotId": "bot_jkl012",
    "idToken": "token_mno345",
    "language": "DE",
    "operatorId": "op_pqr678",
    "photoUrl": "https://example.com/photos/user123.jpg",
    "sessionCount": 3,
    "tags": [
      "vip",
      "sales"
    ],
    "unread": true,
    "variables": {
      "customer_name": "John",
      "order_id": "12345"
    },
    "lastBlock": {
      "id": "blk_abc123",
      "name": "Welcome Message"
    },
    "lastButton": {
      "id": "blk_abc123",
      "name": "Welcome Message"
    },
    "created": "2025-10-05T10:00:00Z",
    "updated": "2025-10-05T12:30:00Z",
    "providerId": "wa_123456789",
    "name": "John Doe",
    "lastMessage": {
      "text": "text",
      "file": {
        "name": "text",
        "url": "text",
        "type": "text",
        "mimeType": "text",
        "size": 1,
        "attachmentRef": "text",
        "caption": "text",
        "transcript": "text"
      },
      "buttons": {
        "buttons": [
          {
            "label": "text",
            "type": "text",
            "value": "text",
            "payload": "text"
          }
        ]
      },
      "selectedButton": {
        "label": "text",
        "value": "text",
        "payload": "text",
        "type": "text",
        "reference": "text"
      },
      "template": {
        "body": "text",
        "header": "text",
        "footer": "text"
      },
      "contact": {
        "addresses": [
          {
            "city": "text",
            "country": "text",
            "countryCode": "text",
            "street": "text",
            "type": "text",
            "zip": "text"
          }
        ],
        "emails": [
          {
            "email": "[e-mail]",
            "type": "text"
          }
        ],
        "name": {
          "firstName": "text",
          "formattedName": "text",
          "lastName": "text"
        },
        "org": {
          "company": "text",
          "title": "text"
        },
        "phones": [
          {
            "phone": "text",
            "type": "text",
            "waId": "text"
          }
        ]
      },
      "location": {
        "latitude": 1,
        "longitude": 1
      },
      "note": {
        "text": "text",
        "mentions": [
          "text"
        ]
      },
      "voiceHangup": {
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "voiceTransfer": {
        "target": "text",
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "agentHandover": {
        "reason": "text",
        "timeoutSeconds": 1,
        "agentId": "text",
        "groupId": "text",
        "assignmentMethod": "text"
      },
      "email": {
        "subject": "text",
        "body": "text",
        "from": "text",
        "to": [
          "text"
        ],
        "cc": [
          "text"
        ],
        "bcc": [
          "text"
        ],
        "attachmentIds": [
          "text"
        ],
        "references": [
          "text"
        ],
        "attachments": [
          {
            "id": "att_123",
            "name": "invoice.pdf",
            "created": "2024-01-01T00:00:00Z",
            "updated": "2024-01-01T00:00:00Z",
            "size": 102400,
            "contentType": "application/pdf",
            "selfLink": "bucketId-objectId/filename.filetype",
            "metadata": {
              "source": "email"
            }
          }
        ]
      },
      "transcription": {
        "text": "text",
        "language": "text",
        "audioRef": "text"
      },
      "textToSpeech": {
        "text": "text",
        "speech": "text"
      },
      "reaction": {
        "reactionToMid": "text",
        "action": "text",
        "reaction": "text",
        "emoji": "text"
      },
      "callSettings": {
        "userInputSpeechDetectionTimeout": 1,
        "dtmf": true,
        "bargeIn": true
      },
      "metaWhatsappTemplate": {
        "templateName": "order_shipped_notification",
        "language": "DE",
        "bodyText": "Your order {{1}} has been shipped.",
        "headerText": "text",
        "footerText": "text",
        "header": {
          "file": {
            "name": "header_image.png",
            "url": "https://storage.example.com/files/header.png",
            "type": "image",
            "mimeType": "image/png",
            "size": 51200,
            "attachmentRef": "att_header123"
          },
          "parameters": [
            "Order #12345"
          ]
        },
        "bodyParameters": [
          "#12345"
        ],
        "buttons": [
          {
            "label": "Track Order",
            "type": "URL",
            "url": "https://example.com/track/{{1}}",
            "value": "track_order"
          }
        ]
      },
      "operator": {
        "operatorId": "op_abc123xyz"
      },
      "delay": 1,
      "leadAiId": "text"
    },
    "snoozed": "2025-10-06T09:00:00Z",
    "lastUserAction": "2025-10-05T12:25:00Z",
    "mentions": [
      "user_123",
      "user_456"
    ],
    "mentionsRead": {
      "user_123": true,
      "user_456": false
    },
    "notes": {
      "notes": [
        "Customer prefers email contact",
        "VIP customer"
      ]
    },
    "lastSender": "user",
    "userInput": {
      "redirect": "flow_abc123",
      "isSensitive": false
    },
    "environment": "test",
    "metadata": {
      "source": "website",
      "campaign": "summer_sale"
    },
    "lastUserInput": "I need help with my order",
    "leadAiConversation": {
      "flowId": "flow_xyz789",
      "stepId": "step_abc123",
      "interactions": 5,
      "executionId": "exec_def456"
    },
    "team": {
      "teamId": "team_support_01"
    },
    "state": 0,
    "lastAssignedOperatorId": "op_xyz789",
    "lastSeen": "2025-10-05T12:30:00Z"
  },
  "error": "text"
}

Retrieves a specific conversation

get

Required Permission: chatbots.conversations.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

conversationIdstringRequired

The Id of the conversation to be retrieved.

Responses

200

The retrieved conversation.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get/v1/chatbots/{chatbotId}/conversations/{conversationId}

GET /v1/chatbots/{chatbotId}/conversations/{conversationId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "conversation": {
    "id": "conv_abc123xyz",
    "contactId": "contact_def456",
    "archived": false,
    "channelId": "channel_ghi789",
    "channelType": "whatsapp",
    "chatbotId": "bot_jkl012",
    "idToken": "token_mno345",
    "language": "DE",
    "operatorId": "op_pqr678",
    "photoUrl": "https://example.com/photos/user123.jpg",
    "sessionCount": 3,
    "tags": [
      "vip",
      "sales"
    ],
    "unread": true,
    "variables": {
      "customer_name": "John",
      "order_id": "12345"
    },
    "lastBlock": {
      "id": "blk_abc123",
      "name": "Welcome Message"
    },
    "lastButton": {
      "id": "blk_abc123",
      "name": "Welcome Message"
    },
    "created": "2025-10-05T10:00:00Z",
    "updated": "2025-10-05T12:30:00Z",
    "providerId": "wa_123456789",
    "name": "John Doe",
    "lastMessage": {
      "text": "text",
      "file": {
        "name": "text",
        "url": "text",
        "type": "text",
        "mimeType": "text",
        "size": 1,
        "attachmentRef": "text",
        "caption": "text",
        "transcript": "text"
      },
      "buttons": {
        "buttons": [
          {
            "label": "text",
            "type": "text",
            "value": "text",
            "payload": "text"
          }
        ]
      },
      "selectedButton": {
        "label": "text",
        "value": "text",
        "payload": "text",
        "type": "text",
        "reference": "text"
      },
      "template": {
        "body": "text",
        "header": "text",
        "footer": "text"
      },
      "contact": {
        "addresses": [
          {
            "city": "text",
            "country": "text",
            "countryCode": "text",
            "street": "text",
            "type": "text",
            "zip": "text"
          }
        ],
        "emails": [
          {
            "email": "[e-mail]",
            "type": "text"
          }
        ],
        "name": {
          "firstName": "text",
          "formattedName": "text",
          "lastName": "text"
        },
        "org": {
          "company": "text",
          "title": "text"
        },
        "phones": [
          {
            "phone": "text",
            "type": "text",
            "waId": "text"
          }
        ]
      },
      "location": {
        "latitude": 1,
        "longitude": 1
      },
      "note": {
        "text": "text",
        "mentions": [
          "text"
        ]
      },
      "voiceHangup": {
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "voiceTransfer": {
        "target": "text",
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "agentHandover": {
        "reason": "text",
        "timeoutSeconds": 1,
        "agentId": "text",
        "groupId": "text",
        "assignmentMethod": "text"
      },
      "email": {
        "subject": "text",
        "body": "text",
        "from": "text",
        "to": [
          "text"
        ],
        "cc": [
          "text"
        ],
        "bcc": [
          "text"
        ],
        "attachmentIds": [
          "text"
        ],
        "references": [
          "text"
        ],
        "attachments": [
          {
            "id": "att_123",
            "name": "invoice.pdf",
            "created": "2024-01-01T00:00:00Z",
            "updated": "2024-01-01T00:00:00Z",
            "size": 102400,
            "contentType": "application/pdf",
            "selfLink": "bucketId-objectId/filename.filetype",
            "metadata": {
              "source": "email"
            }
          }
        ]
      },
      "transcription": {
        "text": "text",
        "language": "text",
        "audioRef": "text"
      },
      "textToSpeech": {
        "text": "text",
        "speech": "text"
      },
      "reaction": {
        "reactionToMid": "text",
        "action": "text",
        "reaction": "text",
        "emoji": "text"
      },
      "callSettings": {
        "userInputSpeechDetectionTimeout": 1,
        "dtmf": true,
        "bargeIn": true
      },
      "metaWhatsappTemplate": {
        "templateName": "order_shipped_notification",
        "language": "DE",
        "bodyText": "Your order {{1}} has been shipped.",
        "headerText": "text",
        "footerText": "text",
        "header": {
          "file": {
            "name": "header_image.png",
            "url": "https://storage.example.com/files/header.png",
            "type": "image",
            "mimeType": "image/png",
            "size": 51200,
            "attachmentRef": "att_header123"
          },
          "parameters": [
            "Order #12345"
          ]
        },
        "bodyParameters": [
          "#12345"
        ],
        "buttons": [
          {
            "label": "Track Order",
            "type": "URL",
            "url": "https://example.com/track/{{1}}",
            "value": "track_order"
          }
        ]
      },
      "operator": {
        "operatorId": "op_abc123xyz"
      },
      "delay": 1,
      "leadAiId": "text"
    },
    "snoozed": "2025-10-06T09:00:00Z",
    "lastUserAction": "2025-10-05T12:25:00Z",
    "mentions": [
      "user_123",
      "user_456"
    ],
    "mentionsRead": {
      "user_123": true,
      "user_456": false
    },
    "notes": {
      "notes": [
        "Customer prefers email contact",
        "VIP customer"
      ]
    },
    "lastSender": "user",
    "userInput": {
      "redirect": "flow_abc123",
      "isSensitive": false
    },
    "environment": "test",
    "metadata": {
      "source": "website",
      "campaign": "summer_sale"
    },
    "lastUserInput": "I need help with my order",
    "leadAiConversation": {
      "flowId": "flow_xyz789",
      "stepId": "step_abc123",
      "interactions": 5,
      "executionId": "exec_def456"
    },
    "team": {
      "teamId": "team_support_01"
    },
    "state": 0,
    "lastAssignedOperatorId": "op_xyz789",
    "lastSeen": "2025-10-05T12:30:00Z"
  },
  "error": "text"
}

Deletes a conversation

delete

Required Permission: chatbots.conversations.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

conversationIdstringRequired

The Id of the conversation to be deleted.

Responses

200Success

application/json

deletedbooleanOptional

Indicates whether the deletion was successful.

Example: true

errorstringOptional

Optional error message.

403

Insufficient permissions.

delete/v1/chatbots/{chatbotId}/conversations/{conversationId}

DELETE /v1/chatbots/{chatbotId}/conversations/{conversationId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "deleted": true,
  "error": "text"
}

Updates an existing conversation

patch

Required Permission: chatbots.conversations.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

conversationIdstringRequired

The Id of the conversation to be updated.

Body

Responses

200Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

patch/v1/chatbots/{chatbotId}/conversations/{conversationId}

PATCH /v1/chatbots/{chatbotId}/conversations/{conversationId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 3409

{
  "conversation": {
    "contactId": "contact_xyz789",
    "archived": true,
    "idToken": "token_abc123",
    "language": "en",
    "operatorId": "op_def456",
    "photoUrl": "https://example.com/photos/user123.jpg",
    "sessionCount": 5,
    "tags": {
      "tags": [
        "priority",
        "sales"
      ]
    },
    "unread": false,
    "lastBlock": {
      "id": "blk_abc123",
      "name": "Welcome Message"
    },
    "lastButton": {
      "id": "btn_abc123",
      "text": "Learn More",
      "value": "learn_more_clicked"
    },
    "providerId": "wa_987654321",
    "lastMessage": {
      "text": "text",
      "file": {
        "name": "text",
        "url": "text",
        "type": "text",
        "mimeType": "text",
        "size": 1,
        "attachmentRef": "text",
        "caption": "text",
        "transcript": "text"
      },
      "buttons": {
        "buttons": [
          {
            "label": "text",
            "type": "text",
            "value": "text",
            "payload": "text"
          }
        ]
      },
      "selectedButton": {
        "label": "text",
        "value": "text",
        "payload": "text",
        "type": "text",
        "reference": "text"
      },
      "template": {
        "body": "text",
        "header": "text",
        "footer": "text"
      },
      "contact": {
        "addresses": [
          {
            "city": "text",
            "country": "text",
            "countryCode": "text",
            "street": "text",
            "type": "text",
            "zip": "text"
          }
        ],
        "emails": [
          {
            "email": "[e-mail]",
            "type": "text"
          }
        ],
        "name": {
          "firstName": "text",
          "formattedName": "text",
          "lastName": "text"
        },
        "org": {
          "company": "text",
          "title": "text"
        },
        "phones": [
          {
            "phone": "text",
            "type": "text",
            "waId": "text"
          }
        ]
      },
      "location": {
        "latitude": 1,
        "longitude": 1
      },
      "note": {
        "text": "text",
        "mentions": [
          "text"
        ]
      },
      "voiceHangup": {
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "voiceTransfer": {
        "target": "text",
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "agentHandover": {
        "reason": "text",
        "timeoutSeconds": 1,
        "agentId": "text",
        "groupId": "text",
        "assignmentMethod": "text"
      },
      "email": {
        "subject": "text",
        "body": "text",
        "from": "text",
        "to": [
          "text"
        ],
        "cc": [
          "text"
        ],
        "bcc": [
          "text"
        ],
        "attachmentIds": [
          "text"
        ],
        "references": [
          "text"
        ],
        "attachments": [
          {
            "id": "att_123",
            "name": "invoice.pdf",
            "created": "2024-01-01T00:00:00Z",
            "updated": "2024-01-01T00:00:00Z",
            "size": 102400,
            "contentType": "application/pdf",
            "selfLink": "bucketId-objectId/filename.filetype",
            "metadata": {
              "source": "email"
            }
          }
        ]
      },
      "transcription": {
        "text": "text",
        "language": "text",
        "audioRef": "text"
      },
      "textToSpeech": {
        "text": "text",
        "speech": "text"
      },
      "reaction": {
        "reactionToMid": "text",
        "action": "text",
        "reaction": "text",
        "emoji": "text"
      },
      "callSettings": {
        "userInputSpeechDetectionTimeout": 1,
        "dtmf": true,
        "bargeIn": true
      },
      "metaWhatsappTemplate": {
        "templateName": "order_shipped_notification",
        "language": "DE",
        "bodyText": "Your order {{1}} has been shipped.",
        "headerText": "text",
        "footerText": "text",
        "header": {
          "file": {
            "name": "header_image.png",
            "url": "https://storage.example.com/files/header.png",
            "type": "image",
            "mimeType": "image/png",
            "size": 51200,
            "attachmentRef": "att_header123"
          },
          "parameters": [
            "Order #12345"
          ]
        },
        "bodyParameters": [
          "#12345"
        ],
        "buttons": [
          {
            "label": "Track Order",
            "type": "URL",
            "url": "https://example.com/track/{{1}}",
            "value": "track_order"
          }
        ]
      },
      "operator": {
        "operatorId": "op_abc123xyz"
      },
      "delay": 1,
      "leadAiId": "text"
    },
    "notes": {
      "notes": [
        "Customer escalated to supervisor"
      ]
    },
    "snoozed": "2025-10-07T09:00:00Z",
    "lastUserAction": "2025-10-05T14:30:00Z",
    "mentions": {
      "mentions": [
        "user_789"
      ]
    },
    "lastSender": "operator",
    "name": "Jane Doe",
    "userInput": {
      "redirect": "flow_xyz789",
      "isSensitive": true
    },
    "metadata": {
      "metadata": {
        "source": "website",
        "campaign": "summer_sale"
      }
    },
    "leadAiConversation": {
      "flowId": "flow_abc123",
      "stepId": "step_def456",
      "interactions": 10,
      "executionId": "exec_ghi789"
    },
    "team": {
      "teamId": "team_sales_02"
    },
    "lastUserInput": "I need help with my order",
    "state": 0,
    "lastAssignedOperatorId": "op_ghi789",
    "lastSeen": "2025-10-05T15:00:00Z"
  }
}

{
  "conversation": {
    "id": "conv_abc123xyz",
    "contactId": "contact_def456",
    "archived": false,
    "channelId": "channel_ghi789",
    "channelType": "whatsapp",
    "chatbotId": "bot_jkl012",
    "idToken": "token_mno345",
    "language": "DE",
    "operatorId": "op_pqr678",
    "photoUrl": "https://example.com/photos/user123.jpg",
    "sessionCount": 3,
    "tags": [
      "vip",
      "sales"
    ],
    "unread": true,
    "variables": {
      "customer_name": "John",
      "order_id": "12345"
    },
    "lastBlock": {
      "id": "blk_abc123",
      "name": "Welcome Message"
    },
    "lastButton": {
      "id": "blk_abc123",
      "name": "Welcome Message"
    },
    "created": "2025-10-05T10:00:00Z",
    "updated": "2025-10-05T12:30:00Z",
    "providerId": "wa_123456789",
    "name": "John Doe",
    "lastMessage": {
      "text": "text",
      "file": {
        "name": "text",
        "url": "text",
        "type": "text",
        "mimeType": "text",
        "size": 1,
        "attachmentRef": "text",
        "caption": "text",
        "transcript": "text"
      },
      "buttons": {
        "buttons": [
          {
            "label": "text",
            "type": "text",
            "value": "text",
            "payload": "text"
          }
        ]
      },
      "selectedButton": {
        "label": "text",
        "value": "text",
        "payload": "text",
        "type": "text",
        "reference": "text"
      },
      "template": {
        "body": "text",
        "header": "text",
        "footer": "text"
      },
      "contact": {
        "addresses": [
          {
            "city": "text",
            "country": "text",
            "countryCode": "text",
            "street": "text",
            "type": "text",
            "zip": "text"
          }
        ],
        "emails": [
          {
            "email": "[e-mail]",
            "type": "text"
          }
        ],
        "name": {
          "firstName": "text",
          "formattedName": "text",
          "lastName": "text"
        },
        "org": {
          "company": "text",
          "title": "text"
        },
        "phones": [
          {
            "phone": "text",
            "type": "text",
            "waId": "text"
          }
        ]
      },
      "location": {
        "latitude": 1,
        "longitude": 1
      },
      "note": {
        "text": "text",
        "mentions": [
          "text"
        ]
      },
      "voiceHangup": {
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "voiceTransfer": {
        "target": "text",
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "agentHandover": {
        "reason": "text",
        "timeoutSeconds": 1,
        "agentId": "text",
        "groupId": "text",
        "assignmentMethod": "text"
      },
      "email": {
        "subject": "text",
        "body": "text",
        "from": "text",
        "to": [
          "text"
        ],
        "cc": [
          "text"
        ],
        "bcc": [
          "text"
        ],
        "attachmentIds": [
          "text"
        ],
        "references": [
          "text"
        ],
        "attachments": [
          {
            "id": "att_123",
            "name": "invoice.pdf",
            "created": "2024-01-01T00:00:00Z",
            "updated": "2024-01-01T00:00:00Z",
            "size": 102400,
            "contentType": "application/pdf",
            "selfLink": "bucketId-objectId/filename.filetype",
            "metadata": {
              "source": "email"
            }
          }
        ]
      },
      "transcription": {
        "text": "text",
        "language": "text",
        "audioRef": "text"
      },
      "textToSpeech": {
        "text": "text",
        "speech": "text"
      },
      "reaction": {
        "reactionToMid": "text",
        "action": "text",
        "reaction": "text",
        "emoji": "text"
      },
      "callSettings": {
        "userInputSpeechDetectionTimeout": 1,
        "dtmf": true,
        "bargeIn": true
      },
      "metaWhatsappTemplate": {
        "templateName": "order_shipped_notification",
        "language": "DE",
        "bodyText": "Your order {{1}} has been shipped.",
        "headerText": "text",
        "footerText": "text",
        "header": {
          "file": {
            "name": "header_image.png",
            "url": "https://storage.example.com/files/header.png",
            "type": "image",
            "mimeType": "image/png",
            "size": 51200,
            "attachmentRef": "att_header123"
          },
          "parameters": [
            "Order #12345"
          ]
        },
        "bodyParameters": [
          "#12345"
        ],
        "buttons": [
          {
            "label": "Track Order",
            "type": "URL",
            "url": "https://example.com/track/{{1}}",
            "value": "track_order"
          }
        ]
      },
      "operator": {
        "operatorId": "op_abc123xyz"
      },
      "delay": 1,
      "leadAiId": "text"
    },
    "snoozed": "2025-10-06T09:00:00Z",
    "lastUserAction": "2025-10-05T12:25:00Z",
    "mentions": [
      "user_123",
      "user_456"
    ],
    "mentionsRead": {
      "user_123": true,
      "user_456": false
    },
    "notes": {
      "notes": [
        "Customer prefers email contact",
        "VIP customer"
      ]
    },
    "lastSender": "user",
    "userInput": {
      "redirect": "flow_abc123",
      "isSensitive": false
    },
    "environment": "test",
    "metadata": {
      "source": "website",
      "campaign": "summer_sale"
    },
    "lastUserInput": "I need help with my order",
    "leadAiConversation": {
      "flowId": "flow_xyz789",
      "stepId": "step_abc123",
      "interactions": 5,
      "executionId": "exec_def456"
    },
    "team": {
      "teamId": "team_support_01"
    },
    "state": 0,
    "lastAssignedOperatorId": "op_xyz789",
    "lastSeen": "2025-10-05T12:30:00Z"
  },
  "error": "text"
}

Processes a new incoming message (e.g., from a channel)

post

Required Permission: chatbots.messages.handle

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdanyRequired

The ID of the chatbot.

Body

chatbotIdstringRequired

The ID of the chatbot.

Example: bot_abc123xyz

channelIdstringRequired

The ID of the channel.

Example: channel_def456

channelNamestringRequired

The name of the channel.

Example: WhatsApp Business

providerIdstringRequired

The external provider ID for the conversation.

Example: 49123456789

calleestringOptional

The callee phone number (for voice channels).

Example: [phone]

asyncbooleanOptional

Whether to process the message asynchronously.

Example: false

Responses

201Success

application/json

conversationIdstringRequired

The ID of the affected conversation.

Example: conv_abc123xyz

messageIdstringRequired

The ID of the newly created message.

Example: msg_def456uvw

errorstringOptional

Optional error message.

403

Insufficient permissions.

post/v1/chatbots/{chatbotId}/conversations/handle

POST /v1/chatbots/{chatbotId}/conversations/handle HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 3146

{
  "chatbotId": "bot_abc123xyz",
  "channelId": "channel_def456",
  "channelName": "WhatsApp Business",
  "providerId": "49123456789",
  "message": {
    "providerMessageId": "wamid.abc123xyz",
    "content": {
      "text": "text",
      "file": {
        "name": "text",
        "url": "text",
        "type": "text",
        "mimeType": "text",
        "size": 1,
        "attachmentRef": "text",
        "caption": "text",
        "transcript": "text"
      },
      "buttons": {
        "buttons": [
          {
            "label": "text",
            "type": "text",
            "value": "text",
            "payload": "text"
          }
        ]
      },
      "selectedButton": {
        "label": "text",
        "value": "text",
        "payload": "text",
        "type": "text",
        "reference": "text"
      },
      "template": {
        "body": "text",
        "header": "text",
        "footer": "text"
      },
      "contact": {
        "addresses": [
          {
            "city": "text",
            "country": "text",
            "countryCode": "text",
            "street": "text",
            "type": "text",
            "zip": "text"
          }
        ],
        "emails": [
          {
            "email": "[e-mail]",
            "type": "text"
          }
        ],
        "name": {
          "firstName": "text",
          "formattedName": "text",
          "lastName": "text"
        },
        "org": {
          "company": "text",
          "title": "text"
        },
        "phones": [
          {
            "phone": "text",
            "type": "text",
            "waId": "text"
          }
        ]
      },
      "location": {
        "latitude": 1,
        "longitude": 1
      },
      "note": {
        "text": "text",
        "mentions": [
          "text"
        ]
      },
      "voiceHangup": {
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "voiceTransfer": {
        "target": "text",
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "agentHandover": {
        "reason": "text",
        "timeoutSeconds": 1,
        "agentId": "text",
        "groupId": "text",
        "assignmentMethod": "text"
      },
      "email": {
        "subject": "text",
        "body": "text",
        "from": "text",
        "to": [
          "text"
        ],
        "cc": [
          "text"
        ],
        "bcc": [
          "text"
        ],
        "attachmentIds": [
          "text"
        ],
        "references": [
          "text"
        ],
        "attachments": [
          {
            "id": "att_123",
            "name": "invoice.pdf",
            "created": "2024-01-01T00:00:00Z",
            "updated": "2024-01-01T00:00:00Z",
            "size": 102400,
            "contentType": "application/pdf",
            "selfLink": "bucketId-objectId/filename.filetype",
            "metadata": {
              "source": "email"
            }
          }
        ]
      },
      "transcription": {
        "text": "text",
        "language": "text",
        "audioRef": "text"
      },
      "textToSpeech": {
        "text": "text",
        "speech": "text"
      },
      "reaction": {
        "reactionToMid": "text",
        "action": "text",
        "reaction": "text",
        "emoji": "text"
      },
      "callSettings": {
        "userInputSpeechDetectionTimeout": 1,
        "dtmf": true,
        "bargeIn": true
      },
      "metaWhatsappTemplate": {
        "templateName": "order_shipped_notification",
        "language": "DE",
        "bodyText": "Your order {{1}} has been shipped.",
        "headerText": "text",
        "footerText": "text",
        "header": {
          "file": {
            "name": "header_image.png",
            "url": "https://storage.example.com/files/header.png",
            "type": "image",
            "mimeType": "image/png",
            "size": 51200,
            "attachmentRef": "att_header123"
          },
          "parameters": [
            "Order #12345"
          ]
        },
        "bodyParameters": [
          "#12345"
        ],
        "buttons": [
          {
            "label": "Track Order",
            "type": "URL",
            "url": "https://example.com/track/{{1}}",
            "value": "track_order"
          }
        ]
      },
      "operator": {
        "operatorId": "op_abc123xyz"
      },
      "delay": 1,
      "leadAiId": "text"
    },
    "sender": "user",
    "type": "text",
    "status": "received",
    "created": "2025-10-05T10:00:00Z",
    "outgoing": false,
    "processed": "2025-10-05T10:00:01Z",
    "sent": "2025-10-05T10:00:02Z",
    "received": "2025-10-05T10:00:03Z",
    "read": "2025-10-05T10:01:00Z",
    "contextId": "ctx_abc123",
    "messengerId": "fb_msg_123",
    "detectedLanguage": "en"
  },
  "profileData": {
    "providerProfileId": "49123456789",
    "name": "John Doe",
    "profilePhotoUrl": "https://example.com/photos/profile.jpg",
    "language": "DE",
    "timezone": "Europe/Berlin",
    "email": "[e-mail]",
    "phoneNumber": "[phone]",
    "subject": "Order inquiry"
  },
  "callee": "[phone]",
  "async": false
}

{
  "conversationId": "conv_abc123xyz",
  "messageId": "msg_def456uvw",
  "messages": [
    {
      "id": "msg_abc123xyz",
      "sender": "bot",
      "type": "text",
      "persona": {
        "image": "https://storage.example.com/avatars/support.png",
        "name": "Support Bot"
      },
      "providerMessageId": "wamid.HBgNNDkxNTEyNjAyNTQ1Ng==",
      "status": "delivered",
      "created": "2025-10-06T12:00:00Z",
      "processed": "2025-10-06T12:00:01Z",
      "sent": "2025-10-06T12:00:02Z",
      "received": "2025-10-06T12:00:03Z",
      "read": "2025-10-06T12:00:10Z",
      "outgoing": true,
      "messengerId": "messenger_abc123",
      "contextId": "ctx_xyz789",
      "content": {
        "text": "text",
        "file": {
          "name": "text",
          "url": "text",
          "type": "text",
          "mimeType": "text",
          "size": 1,
          "attachmentRef": "text",
          "caption": "text",
          "transcript": "text"
        },
        "buttons": {
          "buttons": [
            {
              "label": "text",
              "type": "text",
              "value": "text",
              "payload": "text"
            }
          ]
        },
        "selectedButton": {
          "label": "text",
          "value": "text",
          "payload": "text",
          "type": "text",
          "reference": "text"
        },
        "template": {
          "body": "text",
          "header": "text",
          "footer": "text"
        },
        "contact": {
          "addresses": [
            {
              "city": "text",
              "country": "text",
              "countryCode": "text",
              "street": "text",
              "type": "text",
              "zip": "text"
            }
          ],
          "emails": [
            {
              "email": "[e-mail]",
              "type": "text"
            }
          ],
          "name": {
            "firstName": "text",
            "formattedName": "text",
            "lastName": "text"
          },
          "org": {
            "company": "text",
            "title": "text"
          },
          "phones": [
            {
              "phone": "text",
              "type": "text",
              "waId": "text"
            }
          ]
        },
        "location": {
          "latitude": 1,
          "longitude": 1
        },
        "note": {
          "text": "text",
          "mentions": [
            "text"
          ]
        },
        "voiceHangup": {
          "reason": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        },
        "voiceTransfer": {
          "target": "text",
          "reason": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        },
        "agentHandover": {
          "reason": "text",
          "timeoutSeconds": 1,
          "agentId": "text",
          "groupId": "text",
          "assignmentMethod": "text"
        },
        "email": {
          "subject": "text",
          "body": "text",
          "from": "text",
          "to": [
            "text"
          ],
          "cc": [
            "text"
          ],
          "bcc": [
            "text"
          ],
          "attachmentIds": [
            "text"
          ],
          "references": [
            "text"
          ],
          "attachments": [
            {
              "id": "att_123",
              "name": "invoice.pdf",
              "created": "2024-01-01T00:00:00Z",
              "updated": "2024-01-01T00:00:00Z",
              "size": 102400,
              "contentType": "application/pdf",
              "selfLink": "bucketId-objectId/filename.filetype",
              "metadata": {
                "source": "email"
              }
            }
          ]
        },
        "transcription": {
          "text": "text",
          "language": "text",
          "audioRef": "text"
        },
        "textToSpeech": {
          "text": "text",
          "speech": "text"
        },
        "reaction": {
          "reactionToMid": "text",
          "action": "text",
          "reaction": "text",
          "emoji": "text"
        },
        "callSettings": {
          "userInputSpeechDetectionTimeout": 1,
          "dtmf": true,
          "bargeIn": true
        },
        "metaWhatsappTemplate": {
          "templateName": "order_shipped_notification",
          "language": "DE",
          "bodyText": "Your order {{1}} has been shipped.",
          "headerText": "text",
          "footerText": "text",
          "header": {
            "file": {
              "name": "header_image.png",
              "url": "https://storage.example.com/files/header.png",
              "type": "image",
              "mimeType": "image/png",
              "size": 51200,
              "attachmentRef": "att_header123"
            },
            "parameters": [
              "Order #12345"
            ]
          },
          "bodyParameters": [
            "#12345"
          ],
          "buttons": [
            {
              "label": "Track Order",
              "type": "URL",
              "url": "https://example.com/track/{{1}}",
              "value": "track_order"
            }
          ]
        },
        "operator": {
          "operatorId": "op_abc123xyz"
        },
        "delay": 1,
        "leadAiId": "text"
      },
      "tags": [
        "important",
        "follow-up"
      ],
      "error": "text",
      "isSensitive": false,
      "streamGroupId": "stream_abc123",
      "delay": 1000
    }
  ],
  "error": "text"
}

Processes a new incoming event (e.g., "user_seen")

post

Required Permission: chatbots.events.handle

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdanyRequired

The ID of the chatbot.

Body

chatbotIdstringRequired

The ID of the chatbot.

Example: bot_abc123xyz

channelIdstringRequired

The ID of the channel.

Example: channel_def456

channelNamestringRequired

The name of the channel.

Example: WhatsApp Business

providerIdstringRequired

The external provider ID for the conversation.

Example: 49123456789

eventstringRequired

The triggering event.

Example: user_seen_message

calleestringOptional

The callee phone number (for voice channels).

Example: [phone]

asyncbooleanOptional

Whether to process the event asynchronously.

Example: false

Responses

201Success

application/json

conversationIdstringRequired

The ID of the affected conversation.

Example: conv_abc123xyz

messageIdstringRequired

The ID of the newly created message.

Example: msg_def456uvw

errorstringOptional

Optional error message.

403

Insufficient permissions.

post/v1/chatbots/{chatbotId}/conversations/event

POST /v1/chatbots/{chatbotId}/conversations/event HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 440

{
  "chatbotId": "bot_abc123xyz",
  "channelId": "channel_def456",
  "channelName": "WhatsApp Business",
  "providerId": "49123456789",
  "profileData": {
    "providerProfileId": "49123456789",
    "name": "John Doe",
    "profilePhotoUrl": "https://example.com/photos/profile.jpg",
    "language": "DE",
    "timezone": "Europe/Berlin",
    "email": "[e-mail]",
    "phoneNumber": "[phone]",
    "subject": "Order inquiry"
  },
  "event": "user_seen_message",
  "callee": "[phone]",
  "async": false
}

{
  "conversationId": "conv_abc123xyz",
  "messageId": "msg_def456uvw",
  "messages": [
    {
      "id": "msg_abc123xyz",
      "sender": "bot",
      "type": "text",
      "persona": {
        "image": "https://storage.example.com/avatars/support.png",
        "name": "Support Bot"
      },
      "providerMessageId": "wamid.HBgNNDkxNTEyNjAyNTQ1Ng==",
      "status": "delivered",
      "created": "2025-10-06T12:00:00Z",
      "processed": "2025-10-06T12:00:01Z",
      "sent": "2025-10-06T12:00:02Z",
      "received": "2025-10-06T12:00:03Z",
      "read": "2025-10-06T12:00:10Z",
      "outgoing": true,
      "messengerId": "messenger_abc123",
      "contextId": "ctx_xyz789",
      "content": {
        "text": "text",
        "file": {
          "name": "text",
          "url": "text",
          "type": "text",
          "mimeType": "text",
          "size": 1,
          "attachmentRef": "text",
          "caption": "text",
          "transcript": "text"
        },
        "buttons": {
          "buttons": [
            {
              "label": "text",
              "type": "text",
              "value": "text",
              "payload": "text"
            }
          ]
        },
        "selectedButton": {
          "label": "text",
          "value": "text",
          "payload": "text",
          "type": "text",
          "reference": "text"
        },
        "template": {
          "body": "text",
          "header": "text",
          "footer": "text"
        },
        "contact": {
          "addresses": [
            {
              "city": "text",
              "country": "text",
              "countryCode": "text",
              "street": "text",
              "type": "text",
              "zip": "text"
            }
          ],
          "emails": [
            {
              "email": "[e-mail]",
              "type": "text"
            }
          ],
          "name": {
            "firstName": "text",
            "formattedName": "text",
            "lastName": "text"
          },
          "org": {
            "company": "text",
            "title": "text"
          },
          "phones": [
            {
              "phone": "text",
              "type": "text",
              "waId": "text"
            }
          ]
        },
        "location": {
          "latitude": 1,
          "longitude": 1
        },
        "note": {
          "text": "text",
          "mentions": [
            "text"
          ]
        },
        "voiceHangup": {
          "reason": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        },
        "voiceTransfer": {
          "target": "text",
          "reason": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        },
        "agentHandover": {
          "reason": "text",
          "timeoutSeconds": 1,
          "agentId": "text",
          "groupId": "text",
          "assignmentMethod": "text"
        },
        "email": {
          "subject": "text",
          "body": "text",
          "from": "text",
          "to": [
            "text"
          ],
          "cc": [
            "text"
          ],
          "bcc": [
            "text"
          ],
          "attachmentIds": [
            "text"
          ],
          "references": [
            "text"
          ],
          "attachments": [
            {
              "id": "att_123",
              "name": "invoice.pdf",
              "created": "2024-01-01T00:00:00Z",
              "updated": "2024-01-01T00:00:00Z",
              "size": 102400,
              "contentType": "application/pdf",
              "selfLink": "bucketId-objectId/filename.filetype",
              "metadata": {
                "source": "email"
              }
            }
          ]
        },
        "transcription": {
          "text": "text",
          "language": "text",
          "audioRef": "text"
        },
        "textToSpeech": {
          "text": "text",
          "speech": "text"
        },
        "reaction": {
          "reactionToMid": "text",
          "action": "text",
          "reaction": "text",
          "emoji": "text"
        },
        "callSettings": {
          "userInputSpeechDetectionTimeout": 1,
          "dtmf": true,
          "bargeIn": true
        },
        "metaWhatsappTemplate": {
          "templateName": "order_shipped_notification",
          "language": "DE",
          "bodyText": "Your order {{1}} has been shipped.",
          "headerText": "text",
          "footerText": "text",
          "header": {
            "file": {
              "name": "header_image.png",
              "url": "https://storage.example.com/files/header.png",
              "type": "image",
              "mimeType": "image/png",
              "size": 51200,
              "attachmentRef": "att_header123"
            },
            "parameters": [
              "Order #12345"
            ]
          },
          "bodyParameters": [
            "#12345"
          ],
          "buttons": [
            {
              "label": "Track Order",
              "type": "URL",
              "url": "https://example.com/track/{{1}}",
              "value": "track_order"
            }
          ]
        },
        "operator": {
          "operatorId": "op_abc123xyz"
        },
        "delay": 1,
        "leadAiId": "text"
      },
      "tags": [
        "important",
        "follow-up"
      ],
      "error": "text",
      "isSensitive": false,
      "streamGroupId": "stream_abc123",
      "delay": 1000
    }
  ],
  "error": "text"
}

Processes a step payload.

post

Required Permission: chatbots.step-payload.handle

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdanyRequired

The ID of the chatbot.

Body

chatbotIdstringRequired

The ID of the chatbot.

Example: bot_abc123xyz

conversationIdstringRequired

The ID of the conversation.

Example: conv_def456uvw

flowIdstringOptional

The ID of the flow to execute.

Example: flow_ghi789

stepIdstringOptional

The ID of the step to execute.

Example: step_jkl012

eventstringOptional

The event name to trigger.

Example: custom_event

eventPayloadstringOptional

JSON payload for the event.

Example: {"orderId": "12345"}

asyncbooleanOptional

Whether to process asynchronously.

Example: false

isDebugbooleanOptional

Whether this is a debug request.

Example: false

Responses

201Success

application/json

conversationIdstringRequired

The ID of the affected conversation.

Example: conv_abc123xyz

messageIdstringRequired

The ID of the newly created message.

Example: msg_def456uvw

errorstringOptional

Optional error message.

403

Insufficient permissions.

post/v1/chatbots/{chatbotId}/conversations/payload

POST /v1/chatbots/{chatbotId}/conversations/payload HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 204

{
  "chatbotId": "bot_abc123xyz",
  "conversationId": "conv_def456uvw",
  "flowId": "flow_ghi789",
  "stepId": "step_jkl012",
  "event": "custom_event",
  "eventPayload": "{\"orderId\": \"12345\"}",
  "async": false,
  "isDebug": false
}

{
  "conversationId": "conv_abc123xyz",
  "messageId": "msg_def456uvw",
  "messages": [
    {
      "id": "msg_abc123xyz",
      "sender": "bot",
      "type": "text",
      "persona": {
        "image": "https://storage.example.com/avatars/support.png",
        "name": "Support Bot"
      },
      "providerMessageId": "wamid.HBgNNDkxNTEyNjAyNTQ1Ng==",
      "status": "delivered",
      "created": "2025-10-06T12:00:00Z",
      "processed": "2025-10-06T12:00:01Z",
      "sent": "2025-10-06T12:00:02Z",
      "received": "2025-10-06T12:00:03Z",
      "read": "2025-10-06T12:00:10Z",
      "outgoing": true,
      "messengerId": "messenger_abc123",
      "contextId": "ctx_xyz789",
      "content": {
        "text": "text",
        "file": {
          "name": "text",
          "url": "text",
          "type": "text",
          "mimeType": "text",
          "size": 1,
          "attachmentRef": "text",
          "caption": "text",
          "transcript": "text"
        },
        "buttons": {
          "buttons": [
            {
              "label": "text",
              "type": "text",
              "value": "text",
              "payload": "text"
            }
          ]
        },
        "selectedButton": {
          "label": "text",
          "value": "text",
          "payload": "text",
          "type": "text",
          "reference": "text"
        },
        "template": {
          "body": "text",
          "header": "text",
          "footer": "text"
        },
        "contact": {
          "addresses": [
            {
              "city": "text",
              "country": "text",
              "countryCode": "text",
              "street": "text",
              "type": "text",
              "zip": "text"
            }
          ],
          "emails": [
            {
              "email": "[e-mail]",
              "type": "text"
            }
          ],
          "name": {
            "firstName": "text",
            "formattedName": "text",
            "lastName": "text"
          },
          "org": {
            "company": "text",
            "title": "text"
          },
          "phones": [
            {
              "phone": "text",
              "type": "text",
              "waId": "text"
            }
          ]
        },
        "location": {
          "latitude": 1,
          "longitude": 1
        },
        "note": {
          "text": "text",
          "mentions": [
            "text"
          ]
        },
        "voiceHangup": {
          "reason": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        },
        "voiceTransfer": {
          "target": "text",
          "reason": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        },
        "agentHandover": {
          "reason": "text",
          "timeoutSeconds": 1,
          "agentId": "text",
          "groupId": "text",
          "assignmentMethod": "text"
        },
        "email": {
          "subject": "text",
          "body": "text",
          "from": "text",
          "to": [
            "text"
          ],
          "cc": [
            "text"
          ],
          "bcc": [
            "text"
          ],
          "attachmentIds": [
            "text"
          ],
          "references": [
            "text"
          ],
          "attachments": [
            {
              "id": "att_123",
              "name": "invoice.pdf",
              "created": "2024-01-01T00:00:00Z",
              "updated": "2024-01-01T00:00:00Z",
              "size": 102400,
              "contentType": "application/pdf",
              "selfLink": "bucketId-objectId/filename.filetype",
              "metadata": {
                "source": "email"
              }
            }
          ]
        },
        "transcription": {
          "text": "text",
          "language": "text",
          "audioRef": "text"
        },
        "textToSpeech": {
          "text": "text",
          "speech": "text"
        },
        "reaction": {
          "reactionToMid": "text",
          "action": "text",
          "reaction": "text",
          "emoji": "text"
        },
        "callSettings": {
          "userInputSpeechDetectionTimeout": 1,
          "dtmf": true,
          "bargeIn": true
        },
        "metaWhatsappTemplate": {
          "templateName": "order_shipped_notification",
          "language": "DE",
          "bodyText": "Your order {{1}} has been shipped.",
          "headerText": "text",
          "footerText": "text",
          "header": {
            "file": {
              "name": "header_image.png",
              "url": "https://storage.example.com/files/header.png",
              "type": "image",
              "mimeType": "image/png",
              "size": 51200,
              "attachmentRef": "att_header123"
            },
            "parameters": [
              "Order #12345"
            ]
          },
          "bodyParameters": [
            "#12345"
          ],
          "buttons": [
            {
              "label": "Track Order",
              "type": "URL",
              "url": "https://example.com/track/{{1}}",
              "value": "track_order"
            }
          ]
        },
        "operator": {
          "operatorId": "op_abc123xyz"
        },
        "delay": 1,
        "leadAiId": "text"
      },
      "tags": [
        "important",
        "follow-up"
      ],
      "error": "text",
      "isSensitive": false,
      "streamGroupId": "stream_abc123",
      "delay": 1000
    }
  ],
  "error": "text"
}

Triggers a custom event in a conversation

post

Required Permission: chatbots.events.handle

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdanyRequired

The ID of the chatbot.

Body

chatbotIdstringRequired

The ID of the chatbot.

Example: bot_abc123xyz

conversationIdstringRequired

The ID of the conversation.

Example: conv_def456uvw

eventstringRequired

The custom event name to trigger.

Example: order_completed

Responses

201Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

post/v1/chatbots/{chatbotId}/conversations/custom-event

POST /v1/chatbots/{chatbotId}/conversations/custom-event HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "chatbotId": "bot_abc123xyz",
  "conversationId": "conv_def456uvw",
  "event": "order_completed"
}

{
  "error": "text"
}