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

Conversation Contacts

Searches contacts

get

Required Permission: chatbots.contacts.list

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

Query parameters
querystringRequired

The search term.

pagenumberRequired

The page on which to start the seach.

Example: 1
pageSizenumberRequired

The number of pages to return.

Example: 250
hiddenHitsstringOptional

Comma-separated list of IDs to be excluded from the search results.

Responses
200Success
application/json
errorstringOptional

Optional error message.

get/v1/chatbots/{chatbotId}/contacts/search
GET /v1/chatbots/{chatbotId}/contacts/search?query=text&page=1&pageSize=250 HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "results": {
    "facetCounts": [
      {}
    ],
    "found": 42,
    "hits": [
      {
        "contact": {
          "id": "59aBv7wzR9cxd1Pxyz",
          "name": "Max Mustermann",
          "created": "2025-10-05T10:00:00Z",
          "updated": "2025-10-05T10:05:00Z",
          "email": "max.mustermann@example.com",
          "address": {
            "street": "Example Street",
            "country": "Germany",
            "zipcode": "12345",
            "houseNumber": "1a",
            "location": "Berlin"
          },
          "phoneNumber": "+4917612345678",
          "variables": {
            "customer_id": "12345"
          },
          "organizationIds": [
            "uq8BxZaJd2wZR9cxd1P"
          ],
          "whatsappId": "49123456789",
          "telegramId": "123456789",
          "facebookId": "10158123456789012",
          "instagramId": "17841400123456789",
          "avatar": "https://example.com/avatar.png"
        },
        "highlights": [
          {}
        ],
        "textMatch": "John Doe example@email.com"
      }
    ],
    "outOf": 1000,
    "page": 1,
    "searchTimeMs": 15
  },
  "error": "text"
}

Lists all contacts for a chatbot

get

Required Permission: chatbots.contacts.list

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

Query parameters
pageTokenstringOptional

The date after which to filter organizations. Only organizations created before this date will be fetched.

Example: 2025-09-29T07:08:00Z
limitnumberOptional

The amount of contacts to fetch

Responses
200Success
application/json
errorstringOptional

Optional error message.

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

{
  "contacts": [
    {
      "id": "59aBv7wzR9cxd1Pxyz",
      "name": "Max Mustermann",
      "created": "2025-10-05T10:00:00Z",
      "updated": "2025-10-05T10:05:00Z",
      "email": "max.mustermann@example.com",
      "address": {
        "street": "Example Street",
        "country": "Germany",
        "zipcode": "12345",
        "houseNumber": "1a",
        "location": "Berlin"
      },
      "phoneNumber": "+4917612345678",
      "variables": {
        "customer_id": "12345"
      },
      "organizationIds": [
        "uq8BxZaJd2wZR9cxd1P"
      ],
      "whatsappId": "49123456789",
      "telegramId": "123456789",
      "facebookId": "10158123456789012",
      "instagramId": "17841400123456789",
      "avatar": "https://example.com/avatar.png"
    }
  ],
  "error": "text"
}

Creates a new contact

post

Required Permission: chatbots.contacts.create

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

Body
namestringOptional

The name of the contact.

Example: Max Example
languagestringRequired

The language of the contact.

Example: EN
emailstringOptional

The email address of the contact.

Example: max.mustermann@example.com
phoneNumberstringOptional

The phone number of the contact.

Example: +4917612345678
whatsappIdstringOptional

The WhatsApp ID of the contact.

Example: 49123456789
webIdstringOptional

The web channel ID of the contact.

Example: web_abc123xyz
instagramIdstringOptional

The Instagram ID of the contact.

Example: 17841400123456789
facebookIdstringOptional

The Facebook ID of the contact.

Example: 10158123456789012
telegramIdstringOptional

The Telegram ID of the contact.

Example: 123456789
providerIdstringOptional

The ID of the contact with the external provider.

Example: provider_abc123
avatarstring · uriOptional

The URL to the avatar image of the contact.

Example: https://example.com/avatar.png
Responses
201Success
application/json
errorstringOptional

Optional error message.

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

{
  "name": "Max Example",
  "language": "EN",
  "email": "max.mustermann@example.com",
  "phoneNumber": "+4917612345678",
  "whatsappId": "49123456789",
  "webId": "web_abc123xyz",
  "instagramId": "17841400123456789",
  "facebookId": "10158123456789012",
  "telegramId": "123456789",
  "providerId": "provider_abc123",
  "avatar": "https://example.com/avatar.png"
}
{
  "contact": {
    "id": "59aBv7wzR9cxd1Pxyz",
    "name": "Max Mustermann",
    "created": "2025-10-05T10:00:00Z",
    "updated": "2025-10-05T10:05:00Z",
    "email": "max.mustermann@example.com",
    "address": {
      "street": "Example Street",
      "country": "Germany",
      "zipcode": "12345",
      "houseNumber": "1a",
      "location": "Berlin"
    },
    "phoneNumber": "+4917612345678",
    "variables": {
      "customer_id": "12345"
    },
    "organizationIds": [
      "uq8BxZaJd2wZR9cxd1P"
    ],
    "whatsappId": "49123456789",
    "telegramId": "123456789",
    "facebookId": "10158123456789012",
    "instagramId": "17841400123456789",
    "avatar": "https://example.com/avatar.png"
  },
  "error": "text"
}

Retrieves a specific contact

get

Required Permission: chatbots.contacts.get

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

contactIdstringRequired

The Id of the contact to retrieve.

Responses
200Success
application/json
errorstringOptional

Optional error message.

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

{
  "contact": {
    "id": "59aBv7wzR9cxd1Pxyz",
    "name": "Max Mustermann",
    "created": "2025-10-05T10:00:00Z",
    "updated": "2025-10-05T10:05:00Z",
    "email": "max.mustermann@example.com",
    "address": {
      "street": "Example Street",
      "country": "Germany",
      "zipcode": "12345",
      "houseNumber": "1a",
      "location": "Berlin"
    },
    "phoneNumber": "+4917612345678",
    "variables": {
      "customer_id": "12345"
    },
    "organizationIds": [
      "uq8BxZaJd2wZR9cxd1P"
    ],
    "whatsappId": "49123456789",
    "telegramId": "123456789",
    "facebookId": "10158123456789012",
    "instagramId": "17841400123456789",
    "avatar": "https://example.com/avatar.png"
  },
  "error": "text"
}

Deletes a contact

delete

Required Permission: chatbots.contacts.delete

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

contactIdstringRequired

The Id of the contact to delete.

Responses
200Success
application/json
deletedbooleanOptional

Indicates whether the contact was successfully deleted.

Example: true
errorstringOptional

Optional error message.

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

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

Updates an existing contact

patch

Required Permission: chatbots.contacts.edit

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

contactIdstringRequired

The Id of the contact to retrieve.

Body
Responses
200Success
application/json
errorstringOptional

Optional error message.

patch/v1/chatbots/{chatbotId}/contacts/{contactId}
PATCH /v1/chatbots/{chatbotId}/contacts/{contactId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 367

{
  "contact": {
    "name": "Maximilian Example",
    "email": "maximilian.mustermann@example.com",
    "address": {
      "street": "Example Street",
      "country": "Germany",
      "zipcode": "12345",
      "houseNumber": "1a",
      "location": "Berlin"
    },
    "phoneNumber": "+4917612345678",
    "variables": {
      "customer_id": "12345"
    },
    "organizationIds": [
      "uq8BxZaJd2wZR9cxd1P"
    ],
    "avatar": "https://example.com/avatar.png",
    "language": "EN"
  }
}
{
  "contact": {
    "id": "59aBv7wzR9cxd1Pxyz",
    "name": "Max Mustermann",
    "created": "2025-10-05T10:00:00Z",
    "updated": "2025-10-05T10:05:00Z",
    "email": "max.mustermann@example.com",
    "address": {
      "street": "Example Street",
      "country": "Germany",
      "zipcode": "12345",
      "houseNumber": "1a",
      "location": "Berlin"
    },
    "phoneNumber": "+4917612345678",
    "variables": {
      "customer_id": "12345"
    },
    "organizationIds": [
      "uq8BxZaJd2wZR9cxd1P"
    ],
    "whatsappId": "49123456789",
    "telegramId": "123456789",
    "facebookId": "10158123456789012",
    "instagramId": "17841400123456789",
    "avatar": "https://example.com/avatar.png"
  },
  "error": "text"
}

Lists all organizations a contact belongs to

get

Required Permission: chatbots.contacts.get

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

contactIdstringRequired

The Id of the contact to retrieve.

Responses
200Success
application/json
errorstringOptional

Optional error message.

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

{
  "organizations": [
    {
      "id": "39aBv7wzR9cxd1Pxyz",
      "name": "Example Company Ltd.",
      "created": "2025-10-05T12:00:00Z",
      "updated": "2025-10-05T12:05:00Z",
      "email": "contact@examplecompany.de",
      "website": "https://www.examplecompany.de",
      "size": 50,
      "industry": "Software Development",
      "address": {
        "street": "Example Street",
        "country": "Germany",
        "zipcode": "12345",
        "houseNumber": "1a",
        "location": "Berlin"
      },
      "variables": {
        "customer_number": "KD-12345"
      }
    }
  ],
  "error": "text"
}
PreviousConversation MessagesNextConversation Organizations

Last updated