Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Widgets

Lists the messages of a conversation for the widget

get
Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The Id of the chatbot.

conversationIdstringRequired

The Id of the conversation.

Query parameters
tokenstringRequired

The widget token.

Responses
200Success
application/json
errorstringOptional

Optional error message.

get/v1/widget/{chatbotId}/conversations/{conversationId}/messages
GET /v1/widget/{chatbotId}/conversations/{conversationId}/messages?token=text HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*
200Success
{
  "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": "name@gmail.com",
              "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"
}

Creates a new conversation via the widget

post
Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The Id of the chatbot.

Body
widgetTokenstringRequired

The widget authentication token.

Example: widget_token_abc123xyz
channelIdstringRequired

The ID of the channel.

Example: channel_abc123
languagestringRequired

The language code for the conversation.

Example: DE
Responses
201Success
application/json
newWebTokenstringOptional

A new web token if the previous one expired.

Example: new_widget_token_abc123
errorstringOptional

Optional error message.

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

{
  "widgetToken": "widget_token_abc123xyz",
  "channelId": "channel_abc123",
  "language": "DE"
}
{
  "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": "name@gmail.com",
            "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"
  },
  "newWebToken": "new_widget_token_abc123",
  "error": "text"
}

Creates a new contact via the widget

post
Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The Id of the chatbot.

Body
channelIdstringRequired

The ID of the channel.

Example: channel_abc123
channelTokenstringRequired

The channel authentication token.

Example: channel_token_xyz789
originUrlstringRequired

The origin URL where the widget is embedded.

Example: https://example.com/contact
languagestringRequired

The language code for the widget.

Example: DE
Responses
201Success
application/json
contactIdstringOptional

The ID of the newly created contact.

Example: contact_abc123xyz
widgetTokenstringOptional

The widget authentication token for the new contact.

Example: widget_token_xyz789
errorstringOptional

Optional error message.

post/v1/widget/{chatbotId}/contact
POST /v1/widget/{chatbotId}/contact HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "channelId": "channel_abc123",
  "channelToken": "channel_token_xyz789",
  "originUrl": "https://example.com/contact",
  "language": "DE"
}
{
  "contactId": "contact_abc123xyz",
  "widgetToken": "widget_token_xyz789",
  "error": "text"
}
PreviousStorage ObjectsNextModels

Last updated