# Conversation contacts

## Searches contacts

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.list\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts/search":{"get":{"operationId":"ConversationContactController_searchContacts[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"query","required":true,"in":"query","description":"The search term.","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","description":"The page on which to start the seach.","schema":{"type":"number"}},{"name":"pageSize","required":true,"in":"query","description":"The number of pages to return.","schema":{"type":"number"}},{"name":"hiddenHits","required":false,"in":"query","description":"Comma-separated list of IDs to be excluded from the search results.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchContactsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Searches contacts","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"SearchContactsResponseDto":{"type":"object","properties":{"results":{"description":"The search results.","nullable":true,"allOf":[{"$ref":"#/components/schemas/SearchContactResultDto"}]},"error":{"type":"string","description":"Optional error message."}},"required":["results"]},"SearchContactResultDto":{"type":"object","properties":{"facetCounts":{"description":"The facet counts for the search.","type":"array","items":{"type":"object"}},"found":{"type":"number","description":"Total number of results found."},"hits":{"description":"The search result hits.","type":"array","items":{"$ref":"#/components/schemas/SearchResultHitContactDto"}},"outOf":{"type":"number","description":"Total number of documents searched."},"page":{"type":"number","description":"The current page of search results."},"searchTimeMs":{"type":"number","description":"The duration of the search in milliseconds."}},"required":["facetCounts","found","hits","outOf","page","searchTimeMs"]},"SearchResultHitContactDto":{"type":"object","properties":{"contact":{"description":"The matching contact.","allOf":[{"$ref":"#/components/schemas/ContactDto"}]},"highlights":{"description":"List of highlighted match results.","type":"array","items":{"type":"object"}},"textMatch":{"type":"string","description":"A combined string of all text matches."}},"required":["contact","highlights","textMatch"]},"ContactDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the contact."},"name":{"type":"string","description":"The display name of the contact."},"created":{"type":"string","description":"Timestamp when the contact was created."},"updated":{"type":"string","description":"Timestamp when the contact was last updated."},"email":{"type":"string","description":"The email address of the contact."},"address":{"description":"The address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs this contact belongs to.","type":"array","items":{"type":"string"}},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"avatar":{"type":"string","description":"The URL to the contact's avatar image."}},"required":["id","name","created","updated","variables","organizationIds"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}}}}}
```

## Lists all contacts for a chatbot

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.list\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts":{"get":{"operationId":"ConversationContactController_listContacts[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"pageToken","required":false,"in":"query","description":"The date after which to filter organizations. Only organizations created before this date will be fetched.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"The amount of contacts to fetch","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListContactsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all contacts for a chatbot","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListContactsResponseDto":{"type":"object","properties":{"contacts":{"description":"The list of contacts.","type":"array","items":{"$ref":"#/components/schemas/ContactDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["contacts"]},"ContactDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the contact."},"name":{"type":"string","description":"The display name of the contact."},"created":{"type":"string","description":"Timestamp when the contact was created."},"updated":{"type":"string","description":"Timestamp when the contact was last updated."},"email":{"type":"string","description":"The email address of the contact."},"address":{"description":"The address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs this contact belongs to.","type":"array","items":{"type":"string"}},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"avatar":{"type":"string","description":"The URL to the contact's avatar image."}},"required":["id","name","created","updated","variables","organizationIds"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}}}}}
```

## Creates a new contact

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.create\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts":{"post":{"operationId":"ConversationContactController_createContact[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Creates a new contact","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.create`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"CreateContactRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the contact."},"language":{"type":"string","description":"The language of the contact."},"email":{"type":"string","description":"The email address of the contact."},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"webId":{"type":"string","description":"The web channel ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"providerId":{"type":"string","description":"The ID of the contact with the external provider."},"avatar":{"type":"string","format":"uri","description":"The URL to the avatar image of the contact."}},"required":["language"]},"ContactResponseDto":{"type":"object","properties":{"contact":{"description":"The contact.","allOf":[{"$ref":"#/components/schemas/ContactDto"}]},"error":{"type":"string","description":"Optional error message."}}},"ContactDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the contact."},"name":{"type":"string","description":"The display name of the contact."},"created":{"type":"string","description":"Timestamp when the contact was created."},"updated":{"type":"string","description":"Timestamp when the contact was last updated."},"email":{"type":"string","description":"The email address of the contact."},"address":{"description":"The address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs this contact belongs to.","type":"array","items":{"type":"string"}},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"avatar":{"type":"string","description":"The URL to the contact's avatar image."}},"required":["id","name","created","updated","variables","organizationIds"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}}}}}
```

## Retrieves a specific contact

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.get\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts/{contactId}":{"get":{"operationId":"ConversationContactController_getContact[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"contactId","required":true,"in":"path","description":"The Id of the contact to retrieve.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Retrieves a specific contact","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ContactResponseDto":{"type":"object","properties":{"contact":{"description":"The contact.","allOf":[{"$ref":"#/components/schemas/ContactDto"}]},"error":{"type":"string","description":"Optional error message."}}},"ContactDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the contact."},"name":{"type":"string","description":"The display name of the contact."},"created":{"type":"string","description":"Timestamp when the contact was created."},"updated":{"type":"string","description":"Timestamp when the contact was last updated."},"email":{"type":"string","description":"The email address of the contact."},"address":{"description":"The address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs this contact belongs to.","type":"array","items":{"type":"string"}},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"avatar":{"type":"string","description":"The URL to the contact's avatar image."}},"required":["id","name","created","updated","variables","organizationIds"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}}}}}
```

## Deletes a contact

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.delete\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts/{contactId}":{"delete":{"operationId":"ConversationContactController_deleteContact[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"contactId","required":true,"in":"path","description":"The Id of the contact to delete.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteContactResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Deletes a contact","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.delete`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"DeleteContactResponseDto":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Indicates whether the contact was successfully deleted."},"error":{"type":"string","description":"Optional error message."}}}}}}
```

## Updates an existing contact

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.edit\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts/{contactId}":{"patch":{"operationId":"ConversationContactController_updateContact[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"contactId","required":true,"in":"path","description":"The Id of the contact to retrieve.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Updates an existing contact","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.edit`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"UpdateContactRequestDto":{"type":"object","properties":{"contact":{"description":"The contact data to update.","allOf":[{"$ref":"#/components/schemas/UpdateContactDto"}]}},"required":["contact"]},"UpdateContactDto":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the contact."},"email":{"type":"string","description":"The new email address of the contact."},"address":{"description":"The new address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The new phone number of the contact."},"variables":{"type":"object","description":"Custom variables to set on the contact.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs to associate with the contact.","type":"array","items":{"type":"string"}},"avatar":{"type":"string","format":"uri","description":"The URL to the contact's avatar image."},"language":{"type":"string","description":"The language code of the contact."}},"required":["variables","organizationIds"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}},"ContactResponseDto":{"type":"object","properties":{"contact":{"description":"The contact.","allOf":[{"$ref":"#/components/schemas/ContactDto"}]},"error":{"type":"string","description":"Optional error message."}}},"ContactDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the contact."},"name":{"type":"string","description":"The display name of the contact."},"created":{"type":"string","description":"Timestamp when the contact was created."},"updated":{"type":"string","description":"Timestamp when the contact was last updated."},"email":{"type":"string","description":"The email address of the contact."},"address":{"description":"The address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs this contact belongs to.","type":"array","items":{"type":"string"}},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"avatar":{"type":"string","description":"The URL to the contact's avatar image."}},"required":["id","name","created","updated","variables","organizationIds"]}}}}
```

## Lists all organizations a contact belongs to

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.get\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts/{contactId}/organizations":{"get":{"operationId":"ConversationContactController_listContactOrganizations[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"contactId","required":true,"in":"path","description":"The Id of the contact to retrieve.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListContactOrganizationsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all organizations a contact belongs to","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListContactOrganizationsResponseDto":{"type":"object","properties":{"organizations":{"description":"The list of organizations.","type":"array","items":{"$ref":"#/components/schemas/OrganizationDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["organizations"]},"OrganizationDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the organization."},"name":{"type":"string","description":"The name of the organization."},"created":{"type":"string","description":"Timestamp when the organization was created."},"updated":{"type":"string","description":"Timestamp when the organization was last updated."},"email":{"type":"string","format":"email","description":"The email address of the organization."},"website":{"type":"string","format":"uri","description":"The website URL of the organization."},"size":{"type":"number","description":"The number of employees in the organization."},"industry":{"type":"string","description":"The industry of the organization."},"address":{"description":"The address of the organization.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}}},"required":["id","name","created","updated","variables"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chatcaptain.com/api/api-dokumentation/conversation-contacts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.