# Conversation management

## Lists and filters conversations

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation management","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations":{"get":{"operationId":"ConversationController_listConversations[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"contactId","required":false,"in":"query","description":"Filters by a contact ID.","schema":{"type":"string"}},{"name":"channelId","required":false,"in":"query","description":"Filters by a channel ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListConversationsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists and filters conversations","tags":["Conversation management"],"description":"\n\n**Required Permission:** `chatbots.conversations.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListConversationsResponseDto":{"type":"object","properties":{"conversations":{"description":"The list of conversations.","type":"array","items":{"$ref":"#/components/schemas/ConversationDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["conversations"]},"ConversationDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the conversation."},"contactId":{"type":"string","description":"The ID of the contact associated with this conversation."},"archived":{"type":"boolean","description":"Whether the conversation is archived."},"channelId":{"type":"string","description":"The ID of the channel for this conversation."},"channelType":{"type":"string","description":"The type of channel (e.g., web, whatsapp, telegram)."},"chatbotId":{"type":"string","description":"The ID of the chatbot handling this conversation."},"idToken":{"type":"string","description":"The ID token for this conversation."},"language":{"type":"string","description":"The language code of the conversation."},"operatorId":{"type":"string","description":"The ID of the assigned operator."},"photoUrl":{"type":"string","description":"The URL of the contact's photo."},"sessionCount":{"type":"number","description":"The number of sessions in this conversation."},"tags":{"description":"Tags associated with this conversation.","type":"array","items":{"type":"string"}},"unread":{"type":"boolean","description":"Whether the conversation has unread messages."},"variables":{"type":"object","description":"Custom variables for this conversation.","additionalProperties":{"type":"string"}},"lastBlock":{"description":"The last block visited in the flow.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"lastButton":{"description":"The last button clicked by the user.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"created":{"type":"string","description":"Timestamp when the conversation was created."},"updated":{"type":"string","description":"Timestamp when the conversation was last updated."},"providerId":{"type":"string","description":"The external provider ID for this conversation."},"name":{"type":"string","description":"The display name of the contact."},"lastMessage":{"description":"The content of the last message in the conversation.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"snoozed":{"type":"string","description":"Timestamp until which the conversation is snoozed."},"lastUserAction":{"type":"string","description":"Timestamp of the last user action."},"mentions":{"description":"List of user IDs mentioned in this conversation.","type":"array","items":{"type":"string"}},"mentionsRead":{"type":"object","description":"Map of mentions to their read status.","additionalProperties":{"type":"boolean"}},"notes":{"description":"Notes attached to this conversation.","allOf":[{"$ref":"#/components/schemas/ConversationNotesDto"}]},"lastSender":{"type":"string","description":"The type of the last sender (user, bot, operator)."},"userInput":{"description":"Current user input state.","allOf":[{"$ref":"#/components/schemas/ConversationUserInputDto"}]},"environment":{"type":"string","description":"The environment.","enum":["dev","test","prod"]},"metadata":{"type":"object","description":"Custom metadata for this conversation.","additionalProperties":{"type":"string"}},"lastUserInput":{"type":"string","description":"The last user input text."},"leadAiConversation":{"description":"Lead AI conversation state.","allOf":[{"$ref":"#/components/schemas/ConversationLeadAiConversationDto"}]},"team":{"description":"The team assigned to this conversation.","allOf":[{"$ref":"#/components/schemas/ConversationTeamDto"}]},"state":{"description":"The current state of the conversation.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED","allOf":[{"$ref":"#/components/schemas/ConversationStatus"}]},"lastAssignedOperatorId":{"type":"string","description":"The ID of the last assigned operator."},"lastSeen":{"type":"string","description":"Timestamp when the conversation was last seen."}},"required":["id","contactId","archived","channelId","channelType","chatbotId","idToken","language","operatorId","photoUrl","sessionCount","tags","unread","variables","created","updated","name","snoozed","lastUserAction","mentions","mentionsRead","environment","metadata","state"]},"ConversationBlockDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the block."},"name":{"type":"string","description":"The display name of the block."}},"required":["id","name"]},"ContentDto":{"type":"object","properties":{"text":{"type":"string","description":"The text content of the message."},"file":{"description":"A file attachment.","allOf":[{"$ref":"#/components/schemas/MessageContentFileDto"}]},"buttons":{"description":"Interactive buttons for the message.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonsDto"}]},"selectedButton":{"description":"The button selected by the user.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonReplyDto"}]},"template":{"description":"A message template.","allOf":[{"$ref":"#/components/schemas/MessageTemplateDto"}]},"location":{"description":"A location shared in the message.","allOf":[{"$ref":"#/components/schemas/MessageLocationDto"}]},"voiceHangup":{"description":"Voice hangup data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceHangupDto"}]},"voiceTransfer":{"description":"Voice transfer data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceTransferDto"}]},"agentHandover":{"description":"Agent handover data.","allOf":[{"$ref":"#/components/schemas/MessageAgentHandoverDto"}]},"email":{"description":"Email content data.","allOf":[{"$ref":"#/components/schemas/MessageContentEmailDto"}]},"textToSpeech":{"description":"Text-to-speech content data.","allOf":[{"$ref":"#/components/schemas/MessageContentTextToSpeechDto"}]},"metaWhatsappTemplate":{"description":"A Meta WhatsApp template message.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplateDto"}]},"operator":{"description":"Operator data for the message.","allOf":[{"$ref":"#/components/schemas/OperatorDto"}]},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."},"leadAiId":{"type":"string","description":"The ID of the Lead AI associated with this message."}}},"MessageContentFileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, audio)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."},"caption":{"type":"string","description":"An optional caption for the file."},"transcript":{"type":"string","description":"The transcript of audio/video content."},"facebookAttachmentId":{"type":"string","description":"The Facebook attachment ID."},"whatsappAttachmentId":{"type":"string","description":"The WhatsApp attachment ID."},"instagramAttachmentId":{"type":"string","description":"The Instagram attachment ID."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageContentButtonsDto":{"type":"object","properties":{"buttons":{"description":"The list of buttons.","type":"array","items":{"$ref":"#/components/schemas/MessageContentButtonDto"}}},"required":["buttons"]},"MessageContentButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, postback)."},"value":{"type":"string","description":"The value associated with the button."},"payload":{"type":"string","description":"An optional payload for the button."}},"required":["label","type","value"]},"MessageContentButtonReplyDto":{"type":"object","properties":{"label":{"type":"string","description":"The label of the selected button."},"value":{"type":"string","description":"The value of the selected button."},"payload":{"type":"string","description":"An optional payload from the button."},"type":{"type":"string","description":"The type of the button."},"reference":{"type":"string","description":"The reference to the original button message."}},"required":["label","value","reference"]},"MessageTemplateDto":{"type":"object","properties":{"body":{"type":"string","description":"The body text of the template."},"header":{"type":"string","description":"The header text of the template."},"footer":{"type":"string","description":"The footer text of the template."}},"required":["body"]},"MessageLocationDto":{"type":"object","properties":{"latitude":{"type":"number","description":"The latitude coordinate."},"longitude":{"type":"number","description":"The longitude coordinate."}},"required":["latitude","longitude"]},"MessageVoiceHangupDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for hanging up the call."},"headers":{"type":"object","description":"Custom SIP headers for the hangup.","additionalProperties":{"type":"string"}}},"required":["reason","headers"]},"MessageVoiceTransferDto":{"type":"object","properties":{"target":{"type":"string","description":"The target phone number or SIP address for the transfer."},"reason":{"type":"string","description":"The reason for the transfer."},"headers":{"type":"object","description":"Custom SIP headers for the transfer.","additionalProperties":{"type":"string"}}},"required":["target","headers"]},"MessageAgentHandoverDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for the handover to an agent."},"timeoutSeconds":{"type":"number","description":"Timeout in seconds before the handover expires."},"agentId":{"type":"string","description":"The ID of the specific agent to hand over to."},"groupId":{"type":"string","description":"The ID of the agent group to hand over to."},"assignmentMethod":{"type":"string","description":"The method for assigning the agent (e.g., round_robin, least_busy)."}},"required":["reason"]},"MessageContentEmailDto":{"type":"object","properties":{"subject":{"type":"string","description":"The subject of the email."},"body":{"type":"string","description":"The body content of the email."},"from":{"type":"string","description":"The sender email address."},"to":{"description":"The list of recipient email addresses.","type":"array","items":{"type":"string"}},"cc":{"description":"The list of CC recipient email addresses.","type":"array","items":{"type":"string"}},"bcc":{"description":"The list of BCC recipient email addresses.","type":"array","items":{"type":"string"}},"attachmentIds":{"description":"The list of attachment IDs.","type":"array","items":{"type":"string"}},"references":{"description":"The list of email references for threading.","type":"array","items":{"type":"string"}}},"required":["subject","body","from","to","cc","bcc","attachmentIds","references"]},"MessageContentTextToSpeechDto":{"type":"object","properties":{"text":{"type":"string","description":"The text to be converted to speech."},"speech":{"type":"string","description":"Pre-generated speech audio reference."}},"required":["text"]},"MessageMetaWhatsAppTemplateDto":{"type":"object","properties":{"templateName":{"type":"string","description":"The name of the template on Meta."},"language":{"type":"string","description":"The language code of the template."},"bodyText":{"type":"string","description":"The body text of the message. Placeholders are in the form `{{1}}`."},"headerText":{"type":"string","description":"The text in the header (if present)."},"footerText":{"type":"string","description":"The text in the footer (if present)."},"header":{"description":"The header component, which can contain a file or text parameters.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_HeaderDto"}]},"bodyParameters":{"description":"A list of values that replace the placeholders in the `bodyText`.","type":"array","items":{"type":"string"}},"buttons":{"description":"A list of buttons attached to the message.","type":"array","items":{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_ButtonDto"}}},"required":["templateName","language","bodyText","bodyParameters","buttons"]},"MessageMetaWhatsAppTemplate_HeaderDto":{"type":"object","properties":{"file":{"description":"The file attached to the header.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_Header_FileDto"}]},"parameters":{"description":"The list of parameter values for the header placeholders.","type":"array","items":{"type":"string"}}},"required":["parameters"]},"MessageMetaWhatsAppTemplate_Header_FileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, video)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageMetaWhatsAppTemplate_ButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, quick_reply)."},"url":{"type":"string","description":"The URL for URL-type buttons."},"value":{"type":"string","description":"The value for quick_reply-type buttons."}},"required":["label","type"]},"OperatorDto":{"type":"object","properties":{"operatorId":{"type":"string","description":"The unique identifier of the operator."}},"required":["operatorId"]},"ConversationNotesDto":{"type":"object","properties":{"notes":{"description":"List of notes attached to the conversation.","type":"array","items":{"type":"string"}}},"required":["notes"]},"ConversationUserInputDto":{"type":"object","properties":{"redirect":{"type":"string","description":"The redirect destination for user input."},"isSensitive":{"type":"boolean","description":"Whether the user input contains sensitive data."}},"required":["redirect"]},"ConversationLeadAiConversationDto":{"type":"object","properties":{"flowId":{"type":"string","description":"The ID of the flow being executed."},"stepId":{"type":"string","description":"The ID of the current step in the flow."},"interactions":{"type":"number","description":"The number of interactions in this conversation."},"executionId":{"type":"string","description":"The unique execution ID for this conversation flow."}},"required":["flowId","stepId","interactions","executionId"]},"ConversationTeamDto":{"type":"object","properties":{"teamId":{"type":"string","description":"The ID of the team assigned to this conversation."}},"required":["teamId"]},"ConversationStatus":{"type":"number","enum":[0,1,2,3,-1],"description":"The current state of the conversation.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED"}}}}
```

## Creates a new conversation

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation management","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations":{"post":{"operationId":"ConversationController_createConversation[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/CreateConversationRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Creates a new conversation","tags":["Conversation management"],"description":"\n\n**Required Permission:** `chatbots.conversations.create`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"CreateConversationRequestDto":{"type":"object","properties":{"conversation":{"description":"The conversation data to create.","allOf":[{"$ref":"#/components/schemas/CreateConversationDto"}]}},"required":["conversation"]},"CreateConversationDto":{"type":"object","properties":{"contactId":{"type":"string","description":"The ID of the contact for this conversation."},"channelId":{"type":"string","description":"The ID of the channel for this conversation."},"channelType":{"type":"string","description":"The type of channel.","enum":["facebook","voice","audiocodes","web","meta-whatsapp","telegram","brevo","email","debug"]},"name":{"type":"string","description":"The display name of the contact."},"environment":{"type":"string","description":"The environment.","enum":["dev","test","prod"]},"providerId":{"type":"string","description":"The external provider ID for this conversation."},"unread":{"type":"boolean","description":"Whether the conversation has unread messages."},"archived":{"type":"boolean","description":"Whether the conversation is archived."},"tags":{"description":"Tags to attach to the conversation.","allOf":[{"$ref":"#/components/schemas/CreateConversationTagsDto"}]},"notes":{"description":"Notes to attach to the conversation.","allOf":[{"$ref":"#/components/schemas/CreateConversationNotesDto"}]},"lastMessage":{"description":"The content of the last message.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"operatorId":{"type":"string","description":"The ID of the assigned operator."},"snoozed":{"type":"string","description":"Timestamp until which the conversation is snoozed."},"lastUserAction":{"type":"string","description":"Timestamp of the last user action."},"lastSender":{"type":"string","description":"The type of the last sender (user, bot, operator)."},"mentions":{"description":"User mentions for this conversation.","allOf":[{"$ref":"#/components/schemas/CreateConversationMentionsDto"}]},"metadata":{"type":"object","description":"Custom metadata for this conversation.","additionalProperties":{"type":"string"}},"language":{"type":"string","description":"The language code of the conversation."},"lastAssignedOperatorId":{"type":"string","description":"The ID of the last assigned operator."},"lastSeen":{"type":"string","description":"Timestamp when the conversation was last seen."}},"required":["contactId","channelId","channelType","name","environment"]},"CreateConversationTagsDto":{"type":"object","properties":{"tags":{"description":"List of tags to attach to the conversation.","type":"array","items":{"type":"string"}}},"required":["tags"]},"CreateConversationNotesDto":{"type":"object","properties":{"notes":{"description":"List of notes to attach to the conversation.","type":"array","items":{"type":"string"}}},"required":["notes"]},"ContentDto":{"type":"object","properties":{"text":{"type":"string","description":"The text content of the message."},"file":{"description":"A file attachment.","allOf":[{"$ref":"#/components/schemas/MessageContentFileDto"}]},"buttons":{"description":"Interactive buttons for the message.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonsDto"}]},"selectedButton":{"description":"The button selected by the user.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonReplyDto"}]},"template":{"description":"A message template.","allOf":[{"$ref":"#/components/schemas/MessageTemplateDto"}]},"location":{"description":"A location shared in the message.","allOf":[{"$ref":"#/components/schemas/MessageLocationDto"}]},"voiceHangup":{"description":"Voice hangup data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceHangupDto"}]},"voiceTransfer":{"description":"Voice transfer data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceTransferDto"}]},"agentHandover":{"description":"Agent handover data.","allOf":[{"$ref":"#/components/schemas/MessageAgentHandoverDto"}]},"email":{"description":"Email content data.","allOf":[{"$ref":"#/components/schemas/MessageContentEmailDto"}]},"textToSpeech":{"description":"Text-to-speech content data.","allOf":[{"$ref":"#/components/schemas/MessageContentTextToSpeechDto"}]},"metaWhatsappTemplate":{"description":"A Meta WhatsApp template message.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplateDto"}]},"operator":{"description":"Operator data for the message.","allOf":[{"$ref":"#/components/schemas/OperatorDto"}]},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."},"leadAiId":{"type":"string","description":"The ID of the Lead AI associated with this message."}}},"MessageContentFileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, audio)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."},"caption":{"type":"string","description":"An optional caption for the file."},"transcript":{"type":"string","description":"The transcript of audio/video content."},"facebookAttachmentId":{"type":"string","description":"The Facebook attachment ID."},"whatsappAttachmentId":{"type":"string","description":"The WhatsApp attachment ID."},"instagramAttachmentId":{"type":"string","description":"The Instagram attachment ID."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageContentButtonsDto":{"type":"object","properties":{"buttons":{"description":"The list of buttons.","type":"array","items":{"$ref":"#/components/schemas/MessageContentButtonDto"}}},"required":["buttons"]},"MessageContentButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, postback)."},"value":{"type":"string","description":"The value associated with the button."},"payload":{"type":"string","description":"An optional payload for the button."}},"required":["label","type","value"]},"MessageContentButtonReplyDto":{"type":"object","properties":{"label":{"type":"string","description":"The label of the selected button."},"value":{"type":"string","description":"The value of the selected button."},"payload":{"type":"string","description":"An optional payload from the button."},"type":{"type":"string","description":"The type of the button."},"reference":{"type":"string","description":"The reference to the original button message."}},"required":["label","value","reference"]},"MessageTemplateDto":{"type":"object","properties":{"body":{"type":"string","description":"The body text of the template."},"header":{"type":"string","description":"The header text of the template."},"footer":{"type":"string","description":"The footer text of the template."}},"required":["body"]},"MessageLocationDto":{"type":"object","properties":{"latitude":{"type":"number","description":"The latitude coordinate."},"longitude":{"type":"number","description":"The longitude coordinate."}},"required":["latitude","longitude"]},"MessageVoiceHangupDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for hanging up the call."},"headers":{"type":"object","description":"Custom SIP headers for the hangup.","additionalProperties":{"type":"string"}}},"required":["reason","headers"]},"MessageVoiceTransferDto":{"type":"object","properties":{"target":{"type":"string","description":"The target phone number or SIP address for the transfer."},"reason":{"type":"string","description":"The reason for the transfer."},"headers":{"type":"object","description":"Custom SIP headers for the transfer.","additionalProperties":{"type":"string"}}},"required":["target","headers"]},"MessageAgentHandoverDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for the handover to an agent."},"timeoutSeconds":{"type":"number","description":"Timeout in seconds before the handover expires."},"agentId":{"type":"string","description":"The ID of the specific agent to hand over to."},"groupId":{"type":"string","description":"The ID of the agent group to hand over to."},"assignmentMethod":{"type":"string","description":"The method for assigning the agent (e.g., round_robin, least_busy)."}},"required":["reason"]},"MessageContentEmailDto":{"type":"object","properties":{"subject":{"type":"string","description":"The subject of the email."},"body":{"type":"string","description":"The body content of the email."},"from":{"type":"string","description":"The sender email address."},"to":{"description":"The list of recipient email addresses.","type":"array","items":{"type":"string"}},"cc":{"description":"The list of CC recipient email addresses.","type":"array","items":{"type":"string"}},"bcc":{"description":"The list of BCC recipient email addresses.","type":"array","items":{"type":"string"}},"attachmentIds":{"description":"The list of attachment IDs.","type":"array","items":{"type":"string"}},"references":{"description":"The list of email references for threading.","type":"array","items":{"type":"string"}}},"required":["subject","body","from","to","cc","bcc","attachmentIds","references"]},"MessageContentTextToSpeechDto":{"type":"object","properties":{"text":{"type":"string","description":"The text to be converted to speech."},"speech":{"type":"string","description":"Pre-generated speech audio reference."}},"required":["text"]},"MessageMetaWhatsAppTemplateDto":{"type":"object","properties":{"templateName":{"type":"string","description":"The name of the template on Meta."},"language":{"type":"string","description":"The language code of the template."},"bodyText":{"type":"string","description":"The body text of the message. Placeholders are in the form `{{1}}`."},"headerText":{"type":"string","description":"The text in the header (if present)."},"footerText":{"type":"string","description":"The text in the footer (if present)."},"header":{"description":"The header component, which can contain a file or text parameters.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_HeaderDto"}]},"bodyParameters":{"description":"A list of values that replace the placeholders in the `bodyText`.","type":"array","items":{"type":"string"}},"buttons":{"description":"A list of buttons attached to the message.","type":"array","items":{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_ButtonDto"}}},"required":["templateName","language","bodyText","bodyParameters","buttons"]},"MessageMetaWhatsAppTemplate_HeaderDto":{"type":"object","properties":{"file":{"description":"The file attached to the header.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_Header_FileDto"}]},"parameters":{"description":"The list of parameter values for the header placeholders.","type":"array","items":{"type":"string"}}},"required":["parameters"]},"MessageMetaWhatsAppTemplate_Header_FileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, video)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageMetaWhatsAppTemplate_ButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, quick_reply)."},"url":{"type":"string","description":"The URL for URL-type buttons."},"value":{"type":"string","description":"The value for quick_reply-type buttons."}},"required":["label","type"]},"OperatorDto":{"type":"object","properties":{"operatorId":{"type":"string","description":"The unique identifier of the operator."}},"required":["operatorId"]},"CreateConversationMentionsDto":{"type":"object","properties":{"mentions":{"description":"List of user IDs to mention in the conversation.","type":"array","items":{"type":"string"}}},"required":["mentions"]},"ConversationResponseDto":{"type":"object","properties":{"conversation":{"description":"The conversation.","allOf":[{"$ref":"#/components/schemas/ConversationDto"}]},"error":{"type":"string","description":"Optional error message."}}},"ConversationDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the conversation."},"contactId":{"type":"string","description":"The ID of the contact associated with this conversation."},"archived":{"type":"boolean","description":"Whether the conversation is archived."},"channelId":{"type":"string","description":"The ID of the channel for this conversation."},"channelType":{"type":"string","description":"The type of channel (e.g., web, whatsapp, telegram)."},"chatbotId":{"type":"string","description":"The ID of the chatbot handling this conversation."},"idToken":{"type":"string","description":"The ID token for this conversation."},"language":{"type":"string","description":"The language code of the conversation."},"operatorId":{"type":"string","description":"The ID of the assigned operator."},"photoUrl":{"type":"string","description":"The URL of the contact's photo."},"sessionCount":{"type":"number","description":"The number of sessions in this conversation."},"tags":{"description":"Tags associated with this conversation.","type":"array","items":{"type":"string"}},"unread":{"type":"boolean","description":"Whether the conversation has unread messages."},"variables":{"type":"object","description":"Custom variables for this conversation.","additionalProperties":{"type":"string"}},"lastBlock":{"description":"The last block visited in the flow.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"lastButton":{"description":"The last button clicked by the user.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"created":{"type":"string","description":"Timestamp when the conversation was created."},"updated":{"type":"string","description":"Timestamp when the conversation was last updated."},"providerId":{"type":"string","description":"The external provider ID for this conversation."},"name":{"type":"string","description":"The display name of the contact."},"lastMessage":{"description":"The content of the last message in the conversation.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"snoozed":{"type":"string","description":"Timestamp until which the conversation is snoozed."},"lastUserAction":{"type":"string","description":"Timestamp of the last user action."},"mentions":{"description":"List of user IDs mentioned in this conversation.","type":"array","items":{"type":"string"}},"mentionsRead":{"type":"object","description":"Map of mentions to their read status.","additionalProperties":{"type":"boolean"}},"notes":{"description":"Notes attached to this conversation.","allOf":[{"$ref":"#/components/schemas/ConversationNotesDto"}]},"lastSender":{"type":"string","description":"The type of the last sender (user, bot, operator)."},"userInput":{"description":"Current user input state.","allOf":[{"$ref":"#/components/schemas/ConversationUserInputDto"}]},"environment":{"type":"string","description":"The environment.","enum":["dev","test","prod"]},"metadata":{"type":"object","description":"Custom metadata for this conversation.","additionalProperties":{"type":"string"}},"lastUserInput":{"type":"string","description":"The last user input text."},"leadAiConversation":{"description":"Lead AI conversation state.","allOf":[{"$ref":"#/components/schemas/ConversationLeadAiConversationDto"}]},"team":{"description":"The team assigned to this conversation.","allOf":[{"$ref":"#/components/schemas/ConversationTeamDto"}]},"state":{"description":"The current state of the conversation.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED","allOf":[{"$ref":"#/components/schemas/ConversationStatus"}]},"lastAssignedOperatorId":{"type":"string","description":"The ID of the last assigned operator."},"lastSeen":{"type":"string","description":"Timestamp when the conversation was last seen."}},"required":["id","contactId","archived","channelId","channelType","chatbotId","idToken","language","operatorId","photoUrl","sessionCount","tags","unread","variables","created","updated","name","snoozed","lastUserAction","mentions","mentionsRead","environment","metadata","state"]},"ConversationBlockDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the block."},"name":{"type":"string","description":"The display name of the block."}},"required":["id","name"]},"ConversationNotesDto":{"type":"object","properties":{"notes":{"description":"List of notes attached to the conversation.","type":"array","items":{"type":"string"}}},"required":["notes"]},"ConversationUserInputDto":{"type":"object","properties":{"redirect":{"type":"string","description":"The redirect destination for user input."},"isSensitive":{"type":"boolean","description":"Whether the user input contains sensitive data."}},"required":["redirect"]},"ConversationLeadAiConversationDto":{"type":"object","properties":{"flowId":{"type":"string","description":"The ID of the flow being executed."},"stepId":{"type":"string","description":"The ID of the current step in the flow."},"interactions":{"type":"number","description":"The number of interactions in this conversation."},"executionId":{"type":"string","description":"The unique execution ID for this conversation flow."}},"required":["flowId","stepId","interactions","executionId"]},"ConversationTeamDto":{"type":"object","properties":{"teamId":{"type":"string","description":"The ID of the team assigned to this conversation."}},"required":["teamId"]},"ConversationStatus":{"type":"number","enum":[0,1,2,3,-1],"description":"The current state of the conversation.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED"}}}}
```

## Finds a conversation by external Id's

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation management","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/find":{"get":{"operationId":"ConversationController_findConversations[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"channelId","required":true,"in":"query","description":"The Id of the channel.","schema":{"type":"string"}},{"name":"providerId","required":true,"in":"query","description":"The Id of the provider.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindConversationResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Finds a conversation by external Id's","tags":["Conversation management"],"description":"\n\n**Required Permission:** `chatbots.conversations.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"FindConversationResponseDto":{"type":"object","properties":{"conversation":{"description":"The found conversation.","allOf":[{"$ref":"#/components/schemas/ConversationDto"}]},"error":{"type":"string","description":"Optional error message."}}},"ConversationDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the conversation."},"contactId":{"type":"string","description":"The ID of the contact associated with this conversation."},"archived":{"type":"boolean","description":"Whether the conversation is archived."},"channelId":{"type":"string","description":"The ID of the channel for this conversation."},"channelType":{"type":"string","description":"The type of channel (e.g., web, whatsapp, telegram)."},"chatbotId":{"type":"string","description":"The ID of the chatbot handling this conversation."},"idToken":{"type":"string","description":"The ID token for this conversation."},"language":{"type":"string","description":"The language code of the conversation."},"operatorId":{"type":"string","description":"The ID of the assigned operator."},"photoUrl":{"type":"string","description":"The URL of the contact's photo."},"sessionCount":{"type":"number","description":"The number of sessions in this conversation."},"tags":{"description":"Tags associated with this conversation.","type":"array","items":{"type":"string"}},"unread":{"type":"boolean","description":"Whether the conversation has unread messages."},"variables":{"type":"object","description":"Custom variables for this conversation.","additionalProperties":{"type":"string"}},"lastBlock":{"description":"The last block visited in the flow.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"lastButton":{"description":"The last button clicked by the user.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"created":{"type":"string","description":"Timestamp when the conversation was created."},"updated":{"type":"string","description":"Timestamp when the conversation was last updated."},"providerId":{"type":"string","description":"The external provider ID for this conversation."},"name":{"type":"string","description":"The display name of the contact."},"lastMessage":{"description":"The content of the last message in the conversation.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"snoozed":{"type":"string","description":"Timestamp until which the conversation is snoozed."},"lastUserAction":{"type":"string","description":"Timestamp of the last user action."},"mentions":{"description":"List of user IDs mentioned in this conversation.","type":"array","items":{"type":"string"}},"mentionsRead":{"type":"object","description":"Map of mentions to their read status.","additionalProperties":{"type":"boolean"}},"notes":{"description":"Notes attached to this conversation.","allOf":[{"$ref":"#/components/schemas/ConversationNotesDto"}]},"lastSender":{"type":"string","description":"The type of the last sender (user, bot, operator)."},"userInput":{"description":"Current user input state.","allOf":[{"$ref":"#/components/schemas/ConversationUserInputDto"}]},"environment":{"type":"string","description":"The environment.","enum":["dev","test","prod"]},"metadata":{"type":"object","description":"Custom metadata for this conversation.","additionalProperties":{"type":"string"}},"lastUserInput":{"type":"string","description":"The last user input text."},"leadAiConversation":{"description":"Lead AI conversation state.","allOf":[{"$ref":"#/components/schemas/ConversationLeadAiConversationDto"}]},"team":{"description":"The team assigned to this conversation.","allOf":[{"$ref":"#/components/schemas/ConversationTeamDto"}]},"state":{"description":"The current state of the conversation.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED","allOf":[{"$ref":"#/components/schemas/ConversationStatus"}]},"lastAssignedOperatorId":{"type":"string","description":"The ID of the last assigned operator."},"lastSeen":{"type":"string","description":"Timestamp when the conversation was last seen."}},"required":["id","contactId","archived","channelId","channelType","chatbotId","idToken","language","operatorId","photoUrl","sessionCount","tags","unread","variables","created","updated","name","snoozed","lastUserAction","mentions","mentionsRead","environment","metadata","state"]},"ConversationBlockDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the block."},"name":{"type":"string","description":"The display name of the block."}},"required":["id","name"]},"ContentDto":{"type":"object","properties":{"text":{"type":"string","description":"The text content of the message."},"file":{"description":"A file attachment.","allOf":[{"$ref":"#/components/schemas/MessageContentFileDto"}]},"buttons":{"description":"Interactive buttons for the message.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonsDto"}]},"selectedButton":{"description":"The button selected by the user.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonReplyDto"}]},"template":{"description":"A message template.","allOf":[{"$ref":"#/components/schemas/MessageTemplateDto"}]},"location":{"description":"A location shared in the message.","allOf":[{"$ref":"#/components/schemas/MessageLocationDto"}]},"voiceHangup":{"description":"Voice hangup data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceHangupDto"}]},"voiceTransfer":{"description":"Voice transfer data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceTransferDto"}]},"agentHandover":{"description":"Agent handover data.","allOf":[{"$ref":"#/components/schemas/MessageAgentHandoverDto"}]},"email":{"description":"Email content data.","allOf":[{"$ref":"#/components/schemas/MessageContentEmailDto"}]},"textToSpeech":{"description":"Text-to-speech content data.","allOf":[{"$ref":"#/components/schemas/MessageContentTextToSpeechDto"}]},"metaWhatsappTemplate":{"description":"A Meta WhatsApp template message.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplateDto"}]},"operator":{"description":"Operator data for the message.","allOf":[{"$ref":"#/components/schemas/OperatorDto"}]},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."},"leadAiId":{"type":"string","description":"The ID of the Lead AI associated with this message."}}},"MessageContentFileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, audio)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."},"caption":{"type":"string","description":"An optional caption for the file."},"transcript":{"type":"string","description":"The transcript of audio/video content."},"facebookAttachmentId":{"type":"string","description":"The Facebook attachment ID."},"whatsappAttachmentId":{"type":"string","description":"The WhatsApp attachment ID."},"instagramAttachmentId":{"type":"string","description":"The Instagram attachment ID."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageContentButtonsDto":{"type":"object","properties":{"buttons":{"description":"The list of buttons.","type":"array","items":{"$ref":"#/components/schemas/MessageContentButtonDto"}}},"required":["buttons"]},"MessageContentButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, postback)."},"value":{"type":"string","description":"The value associated with the button."},"payload":{"type":"string","description":"An optional payload for the button."}},"required":["label","type","value"]},"MessageContentButtonReplyDto":{"type":"object","properties":{"label":{"type":"string","description":"The label of the selected button."},"value":{"type":"string","description":"The value of the selected button."},"payload":{"type":"string","description":"An optional payload from the button."},"type":{"type":"string","description":"The type of the button."},"reference":{"type":"string","description":"The reference to the original button message."}},"required":["label","value","reference"]},"MessageTemplateDto":{"type":"object","properties":{"body":{"type":"string","description":"The body text of the template."},"header":{"type":"string","description":"The header text of the template."},"footer":{"type":"string","description":"The footer text of the template."}},"required":["body"]},"MessageLocationDto":{"type":"object","properties":{"latitude":{"type":"number","description":"The latitude coordinate."},"longitude":{"type":"number","description":"The longitude coordinate."}},"required":["latitude","longitude"]},"MessageVoiceHangupDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for hanging up the call."},"headers":{"type":"object","description":"Custom SIP headers for the hangup.","additionalProperties":{"type":"string"}}},"required":["reason","headers"]},"MessageVoiceTransferDto":{"type":"object","properties":{"target":{"type":"string","description":"The target phone number or SIP address for the transfer."},"reason":{"type":"string","description":"The reason for the transfer."},"headers":{"type":"object","description":"Custom SIP headers for the transfer.","additionalProperties":{"type":"string"}}},"required":["target","headers"]},"MessageAgentHandoverDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for the handover to an agent."},"timeoutSeconds":{"type":"number","description":"Timeout in seconds before the handover expires."},"agentId":{"type":"string","description":"The ID of the specific agent to hand over to."},"groupId":{"type":"string","description":"The ID of the agent group to hand over to."},"assignmentMethod":{"type":"string","description":"The method for assigning the agent (e.g., round_robin, least_busy)."}},"required":["reason"]},"MessageContentEmailDto":{"type":"object","properties":{"subject":{"type":"string","description":"The subject of the email."},"body":{"type":"string","description":"The body content of the email."},"from":{"type":"string","description":"The sender email address."},"to":{"description":"The list of recipient email addresses.","type":"array","items":{"type":"string"}},"cc":{"description":"The list of CC recipient email addresses.","type":"array","items":{"type":"string"}},"bcc":{"description":"The list of BCC recipient email addresses.","type":"array","items":{"type":"string"}},"attachmentIds":{"description":"The list of attachment IDs.","type":"array","items":{"type":"string"}},"references":{"description":"The list of email references for threading.","type":"array","items":{"type":"string"}}},"required":["subject","body","from","to","cc","bcc","attachmentIds","references"]},"MessageContentTextToSpeechDto":{"type":"object","properties":{"text":{"type":"string","description":"The text to be converted to speech."},"speech":{"type":"string","description":"Pre-generated speech audio reference."}},"required":["text"]},"MessageMetaWhatsAppTemplateDto":{"type":"object","properties":{"templateName":{"type":"string","description":"The name of the template on Meta."},"language":{"type":"string","description":"The language code of the template."},"bodyText":{"type":"string","description":"The body text of the message. Placeholders are in the form `{{1}}`."},"headerText":{"type":"string","description":"The text in the header (if present)."},"footerText":{"type":"string","description":"The text in the footer (if present)."},"header":{"description":"The header component, which can contain a file or text parameters.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_HeaderDto"}]},"bodyParameters":{"description":"A list of values that replace the placeholders in the `bodyText`.","type":"array","items":{"type":"string"}},"buttons":{"description":"A list of buttons attached to the message.","type":"array","items":{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_ButtonDto"}}},"required":["templateName","language","bodyText","bodyParameters","buttons"]},"MessageMetaWhatsAppTemplate_HeaderDto":{"type":"object","properties":{"file":{"description":"The file attached to the header.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_Header_FileDto"}]},"parameters":{"description":"The list of parameter values for the header placeholders.","type":"array","items":{"type":"string"}}},"required":["parameters"]},"MessageMetaWhatsAppTemplate_Header_FileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, video)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageMetaWhatsAppTemplate_ButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, quick_reply)."},"url":{"type":"string","description":"The URL for URL-type buttons."},"value":{"type":"string","description":"The value for quick_reply-type buttons."}},"required":["label","type"]},"OperatorDto":{"type":"object","properties":{"operatorId":{"type":"string","description":"The unique identifier of the operator."}},"required":["operatorId"]},"ConversationNotesDto":{"type":"object","properties":{"notes":{"description":"List of notes attached to the conversation.","type":"array","items":{"type":"string"}}},"required":["notes"]},"ConversationUserInputDto":{"type":"object","properties":{"redirect":{"type":"string","description":"The redirect destination for user input."},"isSensitive":{"type":"boolean","description":"Whether the user input contains sensitive data."}},"required":["redirect"]},"ConversationLeadAiConversationDto":{"type":"object","properties":{"flowId":{"type":"string","description":"The ID of the flow being executed."},"stepId":{"type":"string","description":"The ID of the current step in the flow."},"interactions":{"type":"number","description":"The number of interactions in this conversation."},"executionId":{"type":"string","description":"The unique execution ID for this conversation flow."}},"required":["flowId","stepId","interactions","executionId"]},"ConversationTeamDto":{"type":"object","properties":{"teamId":{"type":"string","description":"The ID of the team assigned to this conversation."}},"required":["teamId"]},"ConversationStatus":{"type":"number","enum":[0,1,2,3,-1],"description":"The current state of the conversation.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED"}}}}
```

## Retrieves a specific conversation

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation management","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/{conversationId}":{"get":{"operationId":"ConversationController_getConversations[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"conversationId","required":true,"in":"path","description":"The Id of the conversation to be retrieved.","schema":{"type":"string"}}],"responses":{"200":{"description":"The retrieved conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Retrieves a specific conversation","tags":["Conversation management"],"description":"\n\n**Required Permission:** `chatbots.conversations.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ConversationResponseDto":{"type":"object","properties":{"conversation":{"description":"The conversation.","allOf":[{"$ref":"#/components/schemas/ConversationDto"}]},"error":{"type":"string","description":"Optional error message."}}},"ConversationDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the conversation."},"contactId":{"type":"string","description":"The ID of the contact associated with this conversation."},"archived":{"type":"boolean","description":"Whether the conversation is archived."},"channelId":{"type":"string","description":"The ID of the channel for this conversation."},"channelType":{"type":"string","description":"The type of channel (e.g., web, whatsapp, telegram)."},"chatbotId":{"type":"string","description":"The ID of the chatbot handling this conversation."},"idToken":{"type":"string","description":"The ID token for this conversation."},"language":{"type":"string","description":"The language code of the conversation."},"operatorId":{"type":"string","description":"The ID of the assigned operator."},"photoUrl":{"type":"string","description":"The URL of the contact's photo."},"sessionCount":{"type":"number","description":"The number of sessions in this conversation."},"tags":{"description":"Tags associated with this conversation.","type":"array","items":{"type":"string"}},"unread":{"type":"boolean","description":"Whether the conversation has unread messages."},"variables":{"type":"object","description":"Custom variables for this conversation.","additionalProperties":{"type":"string"}},"lastBlock":{"description":"The last block visited in the flow.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"lastButton":{"description":"The last button clicked by the user.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"created":{"type":"string","description":"Timestamp when the conversation was created."},"updated":{"type":"string","description":"Timestamp when the conversation was last updated."},"providerId":{"type":"string","description":"The external provider ID for this conversation."},"name":{"type":"string","description":"The display name of the contact."},"lastMessage":{"description":"The content of the last message in the conversation.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"snoozed":{"type":"string","description":"Timestamp until which the conversation is snoozed."},"lastUserAction":{"type":"string","description":"Timestamp of the last user action."},"mentions":{"description":"List of user IDs mentioned in this conversation.","type":"array","items":{"type":"string"}},"mentionsRead":{"type":"object","description":"Map of mentions to their read status.","additionalProperties":{"type":"boolean"}},"notes":{"description":"Notes attached to this conversation.","allOf":[{"$ref":"#/components/schemas/ConversationNotesDto"}]},"lastSender":{"type":"string","description":"The type of the last sender (user, bot, operator)."},"userInput":{"description":"Current user input state.","allOf":[{"$ref":"#/components/schemas/ConversationUserInputDto"}]},"environment":{"type":"string","description":"The environment.","enum":["dev","test","prod"]},"metadata":{"type":"object","description":"Custom metadata for this conversation.","additionalProperties":{"type":"string"}},"lastUserInput":{"type":"string","description":"The last user input text."},"leadAiConversation":{"description":"Lead AI conversation state.","allOf":[{"$ref":"#/components/schemas/ConversationLeadAiConversationDto"}]},"team":{"description":"The team assigned to this conversation.","allOf":[{"$ref":"#/components/schemas/ConversationTeamDto"}]},"state":{"description":"The current state of the conversation.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED","allOf":[{"$ref":"#/components/schemas/ConversationStatus"}]},"lastAssignedOperatorId":{"type":"string","description":"The ID of the last assigned operator."},"lastSeen":{"type":"string","description":"Timestamp when the conversation was last seen."}},"required":["id","contactId","archived","channelId","channelType","chatbotId","idToken","language","operatorId","photoUrl","sessionCount","tags","unread","variables","created","updated","name","snoozed","lastUserAction","mentions","mentionsRead","environment","metadata","state"]},"ConversationBlockDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the block."},"name":{"type":"string","description":"The display name of the block."}},"required":["id","name"]},"ContentDto":{"type":"object","properties":{"text":{"type":"string","description":"The text content of the message."},"file":{"description":"A file attachment.","allOf":[{"$ref":"#/components/schemas/MessageContentFileDto"}]},"buttons":{"description":"Interactive buttons for the message.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonsDto"}]},"selectedButton":{"description":"The button selected by the user.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonReplyDto"}]},"template":{"description":"A message template.","allOf":[{"$ref":"#/components/schemas/MessageTemplateDto"}]},"location":{"description":"A location shared in the message.","allOf":[{"$ref":"#/components/schemas/MessageLocationDto"}]},"voiceHangup":{"description":"Voice hangup data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceHangupDto"}]},"voiceTransfer":{"description":"Voice transfer data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceTransferDto"}]},"agentHandover":{"description":"Agent handover data.","allOf":[{"$ref":"#/components/schemas/MessageAgentHandoverDto"}]},"email":{"description":"Email content data.","allOf":[{"$ref":"#/components/schemas/MessageContentEmailDto"}]},"textToSpeech":{"description":"Text-to-speech content data.","allOf":[{"$ref":"#/components/schemas/MessageContentTextToSpeechDto"}]},"metaWhatsappTemplate":{"description":"A Meta WhatsApp template message.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplateDto"}]},"operator":{"description":"Operator data for the message.","allOf":[{"$ref":"#/components/schemas/OperatorDto"}]},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."},"leadAiId":{"type":"string","description":"The ID of the Lead AI associated with this message."}}},"MessageContentFileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, audio)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."},"caption":{"type":"string","description":"An optional caption for the file."},"transcript":{"type":"string","description":"The transcript of audio/video content."},"facebookAttachmentId":{"type":"string","description":"The Facebook attachment ID."},"whatsappAttachmentId":{"type":"string","description":"The WhatsApp attachment ID."},"instagramAttachmentId":{"type":"string","description":"The Instagram attachment ID."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageContentButtonsDto":{"type":"object","properties":{"buttons":{"description":"The list of buttons.","type":"array","items":{"$ref":"#/components/schemas/MessageContentButtonDto"}}},"required":["buttons"]},"MessageContentButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, postback)."},"value":{"type":"string","description":"The value associated with the button."},"payload":{"type":"string","description":"An optional payload for the button."}},"required":["label","type","value"]},"MessageContentButtonReplyDto":{"type":"object","properties":{"label":{"type":"string","description":"The label of the selected button."},"value":{"type":"string","description":"The value of the selected button."},"payload":{"type":"string","description":"An optional payload from the button."},"type":{"type":"string","description":"The type of the button."},"reference":{"type":"string","description":"The reference to the original button message."}},"required":["label","value","reference"]},"MessageTemplateDto":{"type":"object","properties":{"body":{"type":"string","description":"The body text of the template."},"header":{"type":"string","description":"The header text of the template."},"footer":{"type":"string","description":"The footer text of the template."}},"required":["body"]},"MessageLocationDto":{"type":"object","properties":{"latitude":{"type":"number","description":"The latitude coordinate."},"longitude":{"type":"number","description":"The longitude coordinate."}},"required":["latitude","longitude"]},"MessageVoiceHangupDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for hanging up the call."},"headers":{"type":"object","description":"Custom SIP headers for the hangup.","additionalProperties":{"type":"string"}}},"required":["reason","headers"]},"MessageVoiceTransferDto":{"type":"object","properties":{"target":{"type":"string","description":"The target phone number or SIP address for the transfer."},"reason":{"type":"string","description":"The reason for the transfer."},"headers":{"type":"object","description":"Custom SIP headers for the transfer.","additionalProperties":{"type":"string"}}},"required":["target","headers"]},"MessageAgentHandoverDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for the handover to an agent."},"timeoutSeconds":{"type":"number","description":"Timeout in seconds before the handover expires."},"agentId":{"type":"string","description":"The ID of the specific agent to hand over to."},"groupId":{"type":"string","description":"The ID of the agent group to hand over to."},"assignmentMethod":{"type":"string","description":"The method for assigning the agent (e.g., round_robin, least_busy)."}},"required":["reason"]},"MessageContentEmailDto":{"type":"object","properties":{"subject":{"type":"string","description":"The subject of the email."},"body":{"type":"string","description":"The body content of the email."},"from":{"type":"string","description":"The sender email address."},"to":{"description":"The list of recipient email addresses.","type":"array","items":{"type":"string"}},"cc":{"description":"The list of CC recipient email addresses.","type":"array","items":{"type":"string"}},"bcc":{"description":"The list of BCC recipient email addresses.","type":"array","items":{"type":"string"}},"attachmentIds":{"description":"The list of attachment IDs.","type":"array","items":{"type":"string"}},"references":{"description":"The list of email references for threading.","type":"array","items":{"type":"string"}}},"required":["subject","body","from","to","cc","bcc","attachmentIds","references"]},"MessageContentTextToSpeechDto":{"type":"object","properties":{"text":{"type":"string","description":"The text to be converted to speech."},"speech":{"type":"string","description":"Pre-generated speech audio reference."}},"required":["text"]},"MessageMetaWhatsAppTemplateDto":{"type":"object","properties":{"templateName":{"type":"string","description":"The name of the template on Meta."},"language":{"type":"string","description":"The language code of the template."},"bodyText":{"type":"string","description":"The body text of the message. Placeholders are in the form `{{1}}`."},"headerText":{"type":"string","description":"The text in the header (if present)."},"footerText":{"type":"string","description":"The text in the footer (if present)."},"header":{"description":"The header component, which can contain a file or text parameters.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_HeaderDto"}]},"bodyParameters":{"description":"A list of values that replace the placeholders in the `bodyText`.","type":"array","items":{"type":"string"}},"buttons":{"description":"A list of buttons attached to the message.","type":"array","items":{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_ButtonDto"}}},"required":["templateName","language","bodyText","bodyParameters","buttons"]},"MessageMetaWhatsAppTemplate_HeaderDto":{"type":"object","properties":{"file":{"description":"The file attached to the header.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_Header_FileDto"}]},"parameters":{"description":"The list of parameter values for the header placeholders.","type":"array","items":{"type":"string"}}},"required":["parameters"]},"MessageMetaWhatsAppTemplate_Header_FileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, video)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageMetaWhatsAppTemplate_ButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, quick_reply)."},"url":{"type":"string","description":"The URL for URL-type buttons."},"value":{"type":"string","description":"The value for quick_reply-type buttons."}},"required":["label","type"]},"OperatorDto":{"type":"object","properties":{"operatorId":{"type":"string","description":"The unique identifier of the operator."}},"required":["operatorId"]},"ConversationNotesDto":{"type":"object","properties":{"notes":{"description":"List of notes attached to the conversation.","type":"array","items":{"type":"string"}}},"required":["notes"]},"ConversationUserInputDto":{"type":"object","properties":{"redirect":{"type":"string","description":"The redirect destination for user input."},"isSensitive":{"type":"boolean","description":"Whether the user input contains sensitive data."}},"required":["redirect"]},"ConversationLeadAiConversationDto":{"type":"object","properties":{"flowId":{"type":"string","description":"The ID of the flow being executed."},"stepId":{"type":"string","description":"The ID of the current step in the flow."},"interactions":{"type":"number","description":"The number of interactions in this conversation."},"executionId":{"type":"string","description":"The unique execution ID for this conversation flow."}},"required":["flowId","stepId","interactions","executionId"]},"ConversationTeamDto":{"type":"object","properties":{"teamId":{"type":"string","description":"The ID of the team assigned to this conversation."}},"required":["teamId"]},"ConversationStatus":{"type":"number","enum":[0,1,2,3,-1],"description":"The current state of the conversation.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED"}}}}
```

## Deletes a conversation

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

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

## Updates an existing conversation

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation management","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/{conversationId}":{"patch":{"operationId":"ConversationController_updateConversation[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"conversationId","required":true,"in":"path","description":"The Id of the conversation to be updated.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConversationRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Updates an existing conversation","tags":["Conversation management"],"description":"\n\n**Required Permission:** `chatbots.conversations.edit`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"UpdateConversationRequestDto":{"type":"object","properties":{"conversation":{"description":"The conversation data to update.","allOf":[{"$ref":"#/components/schemas/UpdateConversationDto"}]}},"required":["conversation"]},"UpdateConversationDto":{"type":"object","properties":{"contactId":{"type":"string","description":"The new contact ID."},"archived":{"type":"boolean","description":"Whether to archive the conversation."},"idToken":{"type":"string","description":"The new ID token."},"language":{"type":"string","description":"The new language code."},"operatorId":{"type":"string","description":"The new assigned operator ID."},"photoUrl":{"type":"string","description":"The new photo URL for the contact."},"sessionCount":{"type":"number","description":"The new session count."},"tags":{"description":"Tags to set on the conversation.","allOf":[{"$ref":"#/components/schemas/UpdateConversation_TagsDto"}]},"unread":{"type":"boolean","description":"Whether the conversation has unread messages."},"lastBlock":{"description":"The last visited block in the flow.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"lastButton":{"description":"The last clicked button.","allOf":[{"$ref":"#/components/schemas/ConversationButtonDto"}]},"providerId":{"type":"string","description":"The new external provider ID."},"lastMessage":{"description":"The content of the last message.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"notes":{"description":"Notes to set on the conversation.","allOf":[{"$ref":"#/components/schemas/UpdateConversation_NotesDto"}]},"snoozed":{"type":"string","description":"Timestamp until which the conversation is snoozed."},"lastUserAction":{"type":"string","description":"Timestamp of the last user action."},"mentions":{"description":"User mentions to set on the conversation.","allOf":[{"$ref":"#/components/schemas/UpdateConversation_MentionsDto"}]},"lastSender":{"type":"string","description":"The type of the last sender (user, bot, operator)."},"name":{"type":"string","description":"The new display name of the contact."},"userInput":{"description":"The user input state.","allOf":[{"$ref":"#/components/schemas/UpdateConversation_UserInputDto"}]},"metadata":{"description":"Metadata to set on the conversation.","allOf":[{"$ref":"#/components/schemas/UpdateConversation_MetadataDto"}]},"leadAiConversation":{"description":"Lead AI conversation state.","allOf":[{"$ref":"#/components/schemas/UpdateConversation_LeadAiConversationDto"}]},"team":{"description":"The team to assign to this conversation.","allOf":[{"$ref":"#/components/schemas/UpdateConversation_ConversationTeamDto"}]},"lastUserInput":{"type":"string","description":"The last user input text."},"state":{"description":"The new conversation state.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED","allOf":[{"$ref":"#/components/schemas/ConversationStatus"}]},"lastAssignedOperatorId":{"type":"string","description":"The ID of the last assigned operator."},"lastSeen":{"type":"string","description":"Timestamp when the conversation was last seen."}}},"UpdateConversation_TagsDto":{"type":"object","properties":{"tags":{"description":"The tags to set on the conversation.","type":"array","items":{"type":"string"}}},"required":["tags"]},"ConversationBlockDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the block."},"name":{"type":"string","description":"The display name of the block."}},"required":["id","name"]},"ConversationButtonDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the button."},"text":{"type":"string","description":"The display text of the button."},"value":{"type":"string","description":"The value sent when the button is clicked."}},"required":["id"]},"ContentDto":{"type":"object","properties":{"text":{"type":"string","description":"The text content of the message."},"file":{"description":"A file attachment.","allOf":[{"$ref":"#/components/schemas/MessageContentFileDto"}]},"buttons":{"description":"Interactive buttons for the message.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonsDto"}]},"selectedButton":{"description":"The button selected by the user.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonReplyDto"}]},"template":{"description":"A message template.","allOf":[{"$ref":"#/components/schemas/MessageTemplateDto"}]},"location":{"description":"A location shared in the message.","allOf":[{"$ref":"#/components/schemas/MessageLocationDto"}]},"voiceHangup":{"description":"Voice hangup data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceHangupDto"}]},"voiceTransfer":{"description":"Voice transfer data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceTransferDto"}]},"agentHandover":{"description":"Agent handover data.","allOf":[{"$ref":"#/components/schemas/MessageAgentHandoverDto"}]},"email":{"description":"Email content data.","allOf":[{"$ref":"#/components/schemas/MessageContentEmailDto"}]},"textToSpeech":{"description":"Text-to-speech content data.","allOf":[{"$ref":"#/components/schemas/MessageContentTextToSpeechDto"}]},"metaWhatsappTemplate":{"description":"A Meta WhatsApp template message.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplateDto"}]},"operator":{"description":"Operator data for the message.","allOf":[{"$ref":"#/components/schemas/OperatorDto"}]},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."},"leadAiId":{"type":"string","description":"The ID of the Lead AI associated with this message."}}},"MessageContentFileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, audio)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."},"caption":{"type":"string","description":"An optional caption for the file."},"transcript":{"type":"string","description":"The transcript of audio/video content."},"facebookAttachmentId":{"type":"string","description":"The Facebook attachment ID."},"whatsappAttachmentId":{"type":"string","description":"The WhatsApp attachment ID."},"instagramAttachmentId":{"type":"string","description":"The Instagram attachment ID."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageContentButtonsDto":{"type":"object","properties":{"buttons":{"description":"The list of buttons.","type":"array","items":{"$ref":"#/components/schemas/MessageContentButtonDto"}}},"required":["buttons"]},"MessageContentButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, postback)."},"value":{"type":"string","description":"The value associated with the button."},"payload":{"type":"string","description":"An optional payload for the button."}},"required":["label","type","value"]},"MessageContentButtonReplyDto":{"type":"object","properties":{"label":{"type":"string","description":"The label of the selected button."},"value":{"type":"string","description":"The value of the selected button."},"payload":{"type":"string","description":"An optional payload from the button."},"type":{"type":"string","description":"The type of the button."},"reference":{"type":"string","description":"The reference to the original button message."}},"required":["label","value","reference"]},"MessageTemplateDto":{"type":"object","properties":{"body":{"type":"string","description":"The body text of the template."},"header":{"type":"string","description":"The header text of the template."},"footer":{"type":"string","description":"The footer text of the template."}},"required":["body"]},"MessageLocationDto":{"type":"object","properties":{"latitude":{"type":"number","description":"The latitude coordinate."},"longitude":{"type":"number","description":"The longitude coordinate."}},"required":["latitude","longitude"]},"MessageVoiceHangupDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for hanging up the call."},"headers":{"type":"object","description":"Custom SIP headers for the hangup.","additionalProperties":{"type":"string"}}},"required":["reason","headers"]},"MessageVoiceTransferDto":{"type":"object","properties":{"target":{"type":"string","description":"The target phone number or SIP address for the transfer."},"reason":{"type":"string","description":"The reason for the transfer."},"headers":{"type":"object","description":"Custom SIP headers for the transfer.","additionalProperties":{"type":"string"}}},"required":["target","headers"]},"MessageAgentHandoverDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for the handover to an agent."},"timeoutSeconds":{"type":"number","description":"Timeout in seconds before the handover expires."},"agentId":{"type":"string","description":"The ID of the specific agent to hand over to."},"groupId":{"type":"string","description":"The ID of the agent group to hand over to."},"assignmentMethod":{"type":"string","description":"The method for assigning the agent (e.g., round_robin, least_busy)."}},"required":["reason"]},"MessageContentEmailDto":{"type":"object","properties":{"subject":{"type":"string","description":"The subject of the email."},"body":{"type":"string","description":"The body content of the email."},"from":{"type":"string","description":"The sender email address."},"to":{"description":"The list of recipient email addresses.","type":"array","items":{"type":"string"}},"cc":{"description":"The list of CC recipient email addresses.","type":"array","items":{"type":"string"}},"bcc":{"description":"The list of BCC recipient email addresses.","type":"array","items":{"type":"string"}},"attachmentIds":{"description":"The list of attachment IDs.","type":"array","items":{"type":"string"}},"references":{"description":"The list of email references for threading.","type":"array","items":{"type":"string"}}},"required":["subject","body","from","to","cc","bcc","attachmentIds","references"]},"MessageContentTextToSpeechDto":{"type":"object","properties":{"text":{"type":"string","description":"The text to be converted to speech."},"speech":{"type":"string","description":"Pre-generated speech audio reference."}},"required":["text"]},"MessageMetaWhatsAppTemplateDto":{"type":"object","properties":{"templateName":{"type":"string","description":"The name of the template on Meta."},"language":{"type":"string","description":"The language code of the template."},"bodyText":{"type":"string","description":"The body text of the message. Placeholders are in the form `{{1}}`."},"headerText":{"type":"string","description":"The text in the header (if present)."},"footerText":{"type":"string","description":"The text in the footer (if present)."},"header":{"description":"The header component, which can contain a file or text parameters.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_HeaderDto"}]},"bodyParameters":{"description":"A list of values that replace the placeholders in the `bodyText`.","type":"array","items":{"type":"string"}},"buttons":{"description":"A list of buttons attached to the message.","type":"array","items":{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_ButtonDto"}}},"required":["templateName","language","bodyText","bodyParameters","buttons"]},"MessageMetaWhatsAppTemplate_HeaderDto":{"type":"object","properties":{"file":{"description":"The file attached to the header.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_Header_FileDto"}]},"parameters":{"description":"The list of parameter values for the header placeholders.","type":"array","items":{"type":"string"}}},"required":["parameters"]},"MessageMetaWhatsAppTemplate_Header_FileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, video)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageMetaWhatsAppTemplate_ButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, quick_reply)."},"url":{"type":"string","description":"The URL for URL-type buttons."},"value":{"type":"string","description":"The value for quick_reply-type buttons."}},"required":["label","type"]},"OperatorDto":{"type":"object","properties":{"operatorId":{"type":"string","description":"The unique identifier of the operator."}},"required":["operatorId"]},"UpdateConversation_NotesDto":{"type":"object","properties":{"notes":{"description":"The notes to set on the conversation.","type":"array","items":{"type":"string"}}},"required":["notes"]},"UpdateConversation_MentionsDto":{"type":"object","properties":{"mentions":{"description":"The user IDs to mention in the conversation.","type":"array","items":{"type":"string"}}},"required":["mentions"]},"UpdateConversation_UserInputDto":{"type":"object","properties":{"redirect":{"type":"string","description":"The redirect destination for user input."},"isSensitive":{"type":"boolean","description":"Whether the user input contains sensitive data."}},"required":["redirect"]},"UpdateConversation_MetadataDto":{"type":"object","properties":{"metadata":{"type":"object","description":"The metadata to set on the conversation.","additionalProperties":{"type":"string"}}},"required":["metadata"]},"UpdateConversation_LeadAiConversationDto":{"type":"object","properties":{"flowId":{"type":"string","description":"The ID of the flow being executed."},"stepId":{"type":"string","description":"The ID of the current step in the flow."},"interactions":{"type":"number","description":"The number of interactions in this conversation."},"executionId":{"type":"string","description":"The unique execution ID for this conversation flow."}},"required":["flowId","stepId","interactions","executionId"]},"UpdateConversation_ConversationTeamDto":{"type":"object","properties":{"teamId":{"type":"string","description":"The ID of the team to assign to this conversation."}},"required":["teamId"]},"ConversationStatus":{"type":"number","enum":[0,1,2,3,-1],"description":"The current state of the conversation.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED"},"ConversationResponseDto":{"type":"object","properties":{"conversation":{"description":"The conversation.","allOf":[{"$ref":"#/components/schemas/ConversationDto"}]},"error":{"type":"string","description":"Optional error message."}}},"ConversationDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the conversation."},"contactId":{"type":"string","description":"The ID of the contact associated with this conversation."},"archived":{"type":"boolean","description":"Whether the conversation is archived."},"channelId":{"type":"string","description":"The ID of the channel for this conversation."},"channelType":{"type":"string","description":"The type of channel (e.g., web, whatsapp, telegram)."},"chatbotId":{"type":"string","description":"The ID of the chatbot handling this conversation."},"idToken":{"type":"string","description":"The ID token for this conversation."},"language":{"type":"string","description":"The language code of the conversation."},"operatorId":{"type":"string","description":"The ID of the assigned operator."},"photoUrl":{"type":"string","description":"The URL of the contact's photo."},"sessionCount":{"type":"number","description":"The number of sessions in this conversation."},"tags":{"description":"Tags associated with this conversation.","type":"array","items":{"type":"string"}},"unread":{"type":"boolean","description":"Whether the conversation has unread messages."},"variables":{"type":"object","description":"Custom variables for this conversation.","additionalProperties":{"type":"string"}},"lastBlock":{"description":"The last block visited in the flow.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"lastButton":{"description":"The last button clicked by the user.","allOf":[{"$ref":"#/components/schemas/ConversationBlockDto"}]},"created":{"type":"string","description":"Timestamp when the conversation was created."},"updated":{"type":"string","description":"Timestamp when the conversation was last updated."},"providerId":{"type":"string","description":"The external provider ID for this conversation."},"name":{"type":"string","description":"The display name of the contact."},"lastMessage":{"description":"The content of the last message in the conversation.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"snoozed":{"type":"string","description":"Timestamp until which the conversation is snoozed."},"lastUserAction":{"type":"string","description":"Timestamp of the last user action."},"mentions":{"description":"List of user IDs mentioned in this conversation.","type":"array","items":{"type":"string"}},"mentionsRead":{"type":"object","description":"Map of mentions to their read status.","additionalProperties":{"type":"boolean"}},"notes":{"description":"Notes attached to this conversation.","allOf":[{"$ref":"#/components/schemas/ConversationNotesDto"}]},"lastSender":{"type":"string","description":"The type of the last sender (user, bot, operator)."},"userInput":{"description":"Current user input state.","allOf":[{"$ref":"#/components/schemas/ConversationUserInputDto"}]},"environment":{"type":"string","description":"The environment.","enum":["dev","test","prod"]},"metadata":{"type":"object","description":"Custom metadata for this conversation.","additionalProperties":{"type":"string"}},"lastUserInput":{"type":"string","description":"The last user input text."},"leadAiConversation":{"description":"Lead AI conversation state.","allOf":[{"$ref":"#/components/schemas/ConversationLeadAiConversationDto"}]},"team":{"description":"The team assigned to this conversation.","allOf":[{"$ref":"#/components/schemas/ConversationTeamDto"}]},"state":{"description":"The current state of the conversation.\n\n- `0`: OPEN\n- `1`: BOT\n- `2`: IN_PROGRESS\n- `3`: CLOSED","allOf":[{"$ref":"#/components/schemas/ConversationStatus"}]},"lastAssignedOperatorId":{"type":"string","description":"The ID of the last assigned operator."},"lastSeen":{"type":"string","description":"Timestamp when the conversation was last seen."}},"required":["id","contactId","archived","channelId","channelType","chatbotId","idToken","language","operatorId","photoUrl","sessionCount","tags","unread","variables","created","updated","name","snoozed","lastUserAction","mentions","mentionsRead","environment","metadata","state"]},"ConversationNotesDto":{"type":"object","properties":{"notes":{"description":"List of notes attached to the conversation.","type":"array","items":{"type":"string"}}},"required":["notes"]},"ConversationUserInputDto":{"type":"object","properties":{"redirect":{"type":"string","description":"The redirect destination for user input."},"isSensitive":{"type":"boolean","description":"Whether the user input contains sensitive data."}},"required":["redirect"]},"ConversationLeadAiConversationDto":{"type":"object","properties":{"flowId":{"type":"string","description":"The ID of the flow being executed."},"stepId":{"type":"string","description":"The ID of the current step in the flow."},"interactions":{"type":"number","description":"The number of interactions in this conversation."},"executionId":{"type":"string","description":"The unique execution ID for this conversation flow."}},"required":["flowId","stepId","interactions","executionId"]},"ConversationTeamDto":{"type":"object","properties":{"teamId":{"type":"string","description":"The ID of the team assigned to this conversation."}},"required":["teamId"]}}}}
```

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

> \
> \
> \*\*Required Permission:\*\* \`chatbots.messages.handle\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation management","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/handle":{"post":{"operationId":"ConversationController_handleIncomingMessage[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandleNewIncomingMessageRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandleIncomingResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Processes a new incoming message (e.g., from a channel)","tags":["Conversation management"],"description":"\n\n**Required Permission:** `chatbots.messages.handle`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"HandleNewIncomingMessageRequestDto":{"type":"object","properties":{"chatbotId":{"type":"string","description":"The ID of the chatbot."},"channelId":{"type":"string","description":"The ID of the channel."},"channelName":{"type":"string","description":"The name of the channel."},"providerId":{"type":"string","description":"The external provider ID for the conversation."},"message":{"description":"The incoming message data.","allOf":[{"$ref":"#/components/schemas/HandleNewIncomingMessageRequest_MessageDto"}]},"profileData":{"description":"The user's profile data.","allOf":[{"$ref":"#/components/schemas/HandleNewIncomingMessageRequest_ProfileDataDto"}]},"callee":{"type":"string","description":"The callee phone number (for voice channels)."},"async":{"type":"boolean","description":"Whether to process the message asynchronously."}},"required":["chatbotId","channelId","channelName","providerId","message","profileData"]},"HandleNewIncomingMessageRequest_MessageDto":{"type":"object","properties":{"providerMessageId":{"type":"string","description":"The message ID from the external provider."},"content":{"description":"The content of the message.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"sender":{"type":"string","description":"The sender type (user, bot, operator)."},"type":{"type":"string","description":"The type of message content."},"status":{"type":"string","description":"The delivery status of the message."},"created":{"type":"string","description":"Timestamp when the message was created (ISO format)."},"outgoing":{"type":"boolean","description":"Whether this is an outgoing message."},"processed":{"type":"string","description":"Timestamp when the message was processed."},"sent":{"type":"string","description":"Timestamp when the message was sent."},"received":{"type":"string","description":"Timestamp when the message was received."},"read":{"type":"string","description":"Timestamp when the message was read."},"contextId":{"type":"string","description":"The context ID for message threading."},"messengerId":{"type":"string","description":"The messenger-specific ID."},"detectedLanguage":{"type":"string","description":"The detected language code of the message."}},"required":["providerMessageId","content","sender","type","status","created","outgoing"]},"ContentDto":{"type":"object","properties":{"text":{"type":"string","description":"The text content of the message."},"file":{"description":"A file attachment.","allOf":[{"$ref":"#/components/schemas/MessageContentFileDto"}]},"buttons":{"description":"Interactive buttons for the message.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonsDto"}]},"selectedButton":{"description":"The button selected by the user.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonReplyDto"}]},"template":{"description":"A message template.","allOf":[{"$ref":"#/components/schemas/MessageTemplateDto"}]},"location":{"description":"A location shared in the message.","allOf":[{"$ref":"#/components/schemas/MessageLocationDto"}]},"voiceHangup":{"description":"Voice hangup data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceHangupDto"}]},"voiceTransfer":{"description":"Voice transfer data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceTransferDto"}]},"agentHandover":{"description":"Agent handover data.","allOf":[{"$ref":"#/components/schemas/MessageAgentHandoverDto"}]},"email":{"description":"Email content data.","allOf":[{"$ref":"#/components/schemas/MessageContentEmailDto"}]},"textToSpeech":{"description":"Text-to-speech content data.","allOf":[{"$ref":"#/components/schemas/MessageContentTextToSpeechDto"}]},"metaWhatsappTemplate":{"description":"A Meta WhatsApp template message.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplateDto"}]},"operator":{"description":"Operator data for the message.","allOf":[{"$ref":"#/components/schemas/OperatorDto"}]},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."},"leadAiId":{"type":"string","description":"The ID of the Lead AI associated with this message."}}},"MessageContentFileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, audio)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."},"caption":{"type":"string","description":"An optional caption for the file."},"transcript":{"type":"string","description":"The transcript of audio/video content."},"facebookAttachmentId":{"type":"string","description":"The Facebook attachment ID."},"whatsappAttachmentId":{"type":"string","description":"The WhatsApp attachment ID."},"instagramAttachmentId":{"type":"string","description":"The Instagram attachment ID."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageContentButtonsDto":{"type":"object","properties":{"buttons":{"description":"The list of buttons.","type":"array","items":{"$ref":"#/components/schemas/MessageContentButtonDto"}}},"required":["buttons"]},"MessageContentButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, postback)."},"value":{"type":"string","description":"The value associated with the button."},"payload":{"type":"string","description":"An optional payload for the button."}},"required":["label","type","value"]},"MessageContentButtonReplyDto":{"type":"object","properties":{"label":{"type":"string","description":"The label of the selected button."},"value":{"type":"string","description":"The value of the selected button."},"payload":{"type":"string","description":"An optional payload from the button."},"type":{"type":"string","description":"The type of the button."},"reference":{"type":"string","description":"The reference to the original button message."}},"required":["label","value","reference"]},"MessageTemplateDto":{"type":"object","properties":{"body":{"type":"string","description":"The body text of the template."},"header":{"type":"string","description":"The header text of the template."},"footer":{"type":"string","description":"The footer text of the template."}},"required":["body"]},"MessageLocationDto":{"type":"object","properties":{"latitude":{"type":"number","description":"The latitude coordinate."},"longitude":{"type":"number","description":"The longitude coordinate."}},"required":["latitude","longitude"]},"MessageVoiceHangupDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for hanging up the call."},"headers":{"type":"object","description":"Custom SIP headers for the hangup.","additionalProperties":{"type":"string"}}},"required":["reason","headers"]},"MessageVoiceTransferDto":{"type":"object","properties":{"target":{"type":"string","description":"The target phone number or SIP address for the transfer."},"reason":{"type":"string","description":"The reason for the transfer."},"headers":{"type":"object","description":"Custom SIP headers for the transfer.","additionalProperties":{"type":"string"}}},"required":["target","headers"]},"MessageAgentHandoverDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for the handover to an agent."},"timeoutSeconds":{"type":"number","description":"Timeout in seconds before the handover expires."},"agentId":{"type":"string","description":"The ID of the specific agent to hand over to."},"groupId":{"type":"string","description":"The ID of the agent group to hand over to."},"assignmentMethod":{"type":"string","description":"The method for assigning the agent (e.g., round_robin, least_busy)."}},"required":["reason"]},"MessageContentEmailDto":{"type":"object","properties":{"subject":{"type":"string","description":"The subject of the email."},"body":{"type":"string","description":"The body content of the email."},"from":{"type":"string","description":"The sender email address."},"to":{"description":"The list of recipient email addresses.","type":"array","items":{"type":"string"}},"cc":{"description":"The list of CC recipient email addresses.","type":"array","items":{"type":"string"}},"bcc":{"description":"The list of BCC recipient email addresses.","type":"array","items":{"type":"string"}},"attachmentIds":{"description":"The list of attachment IDs.","type":"array","items":{"type":"string"}},"references":{"description":"The list of email references for threading.","type":"array","items":{"type":"string"}}},"required":["subject","body","from","to","cc","bcc","attachmentIds","references"]},"MessageContentTextToSpeechDto":{"type":"object","properties":{"text":{"type":"string","description":"The text to be converted to speech."},"speech":{"type":"string","description":"Pre-generated speech audio reference."}},"required":["text"]},"MessageMetaWhatsAppTemplateDto":{"type":"object","properties":{"templateName":{"type":"string","description":"The name of the template on Meta."},"language":{"type":"string","description":"The language code of the template."},"bodyText":{"type":"string","description":"The body text of the message. Placeholders are in the form `{{1}}`."},"headerText":{"type":"string","description":"The text in the header (if present)."},"footerText":{"type":"string","description":"The text in the footer (if present)."},"header":{"description":"The header component, which can contain a file or text parameters.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_HeaderDto"}]},"bodyParameters":{"description":"A list of values that replace the placeholders in the `bodyText`.","type":"array","items":{"type":"string"}},"buttons":{"description":"A list of buttons attached to the message.","type":"array","items":{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_ButtonDto"}}},"required":["templateName","language","bodyText","bodyParameters","buttons"]},"MessageMetaWhatsAppTemplate_HeaderDto":{"type":"object","properties":{"file":{"description":"The file attached to the header.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_Header_FileDto"}]},"parameters":{"description":"The list of parameter values for the header placeholders.","type":"array","items":{"type":"string"}}},"required":["parameters"]},"MessageMetaWhatsAppTemplate_Header_FileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, video)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageMetaWhatsAppTemplate_ButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, quick_reply)."},"url":{"type":"string","description":"The URL for URL-type buttons."},"value":{"type":"string","description":"The value for quick_reply-type buttons."}},"required":["label","type"]},"OperatorDto":{"type":"object","properties":{"operatorId":{"type":"string","description":"The unique identifier of the operator."}},"required":["operatorId"]},"HandleNewIncomingMessageRequest_ProfileDataDto":{"type":"object","properties":{"providerProfileId":{"type":"string","description":"The profile ID from the external provider."},"name":{"type":"string","description":"The display name of the user."},"profilePhotoUrl":{"type":"string","description":"The URL of the user's profile photo."},"language":{"type":"string","description":"The user's preferred language code."},"timezone":{"type":"string","description":"The user's timezone."},"email":{"type":"string","description":"The user's email address."},"phoneNumber":{"type":"string","description":"The user's phone number."},"subject":{"type":"string","description":"The subject of the message (for email channels)."}}},"HandleIncomingResponseDto":{"type":"object","properties":{"conversationId":{"type":"string","description":"The ID of the affected conversation."},"messageId":{"type":"string","description":"The ID of the newly created message."},"messages":{"description":"A list of messages generated as a response.","type":"array","items":{"$ref":"#/components/schemas/MessageDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["conversationId","messageId","messages"]},"MessageDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the message."},"sender":{"type":"string","description":"The sender of the message (e.g., user, bot, agent)."},"type":{"type":"string","description":"The type of message (e.g., text, file, template)."},"persona":{"description":"The persona representing the sender.","allOf":[{"$ref":"#/components/schemas/MessagePersonaDto"}]},"providerMessageId":{"type":"string","description":"The message ID from the external provider."},"status":{"type":"string","description":"The delivery status of the message."},"created":{"type":"string","description":"Timestamp when the message was created."},"processed":{"type":"string","description":"Timestamp when the message was processed."},"sent":{"type":"string","description":"Timestamp when the message was sent."},"received":{"type":"string","description":"Timestamp when the message was received by the recipient."},"read":{"type":"string","description":"Timestamp when the message was read by the recipient."},"outgoing":{"type":"boolean","description":"Whether the message is outgoing (true) or incoming (false)."},"messengerId":{"type":"string","description":"The messenger ID associated with the message."},"contextId":{"type":"string","description":"The context ID for message threading."},"content":{"description":"The content of the message.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"tags":{"description":"The list of tags associated with the message.","type":"array","items":{"type":"string"}},"error":{"type":"string","description":"Optional error message."},"isSensitive":{"type":"boolean","description":"Whether the message contains sensitive content."},"streamGroupId":{"type":"string","description":"The stream group ID for grouped streaming messages."},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."}},"required":["id","sender","type","status","created","outgoing","content","tags"]},"MessagePersonaDto":{"type":"object","properties":{"image":{"type":"string","description":"The URL of the persona's avatar image."},"name":{"type":"string","description":"The display name of the persona."}},"required":["image","name"]}}}}
```

## Processes a new incoming event (e.g., "user\_seen")

> \
> \
> \*\*Required Permission:\*\* \`chatbots.events.handle\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation management","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/event":{"post":{"operationId":"ConversationController_handleIncomingEvent[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandleNewIncomingEventRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandleIncomingResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Processes a new incoming event (e.g., \"user_seen\")","tags":["Conversation management"],"description":"\n\n**Required Permission:** `chatbots.events.handle`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"HandleNewIncomingEventRequestDto":{"type":"object","properties":{"chatbotId":{"type":"string","description":"The ID of the chatbot."},"channelId":{"type":"string","description":"The ID of the channel."},"channelName":{"type":"string","description":"The name of the channel."},"providerId":{"type":"string","description":"The external provider ID for the conversation."},"profileData":{"description":"The user's profile data.","allOf":[{"$ref":"#/components/schemas/HandleNewIncomingMessageRequest_ProfileDataDto"}]},"event":{"type":"string","description":"The triggering event."},"callee":{"type":"string","description":"The callee phone number (for voice channels)."},"async":{"type":"boolean","description":"Whether to process the event asynchronously."}},"required":["chatbotId","channelId","channelName","providerId","profileData","event"]},"HandleNewIncomingMessageRequest_ProfileDataDto":{"type":"object","properties":{"providerProfileId":{"type":"string","description":"The profile ID from the external provider."},"name":{"type":"string","description":"The display name of the user."},"profilePhotoUrl":{"type":"string","description":"The URL of the user's profile photo."},"language":{"type":"string","description":"The user's preferred language code."},"timezone":{"type":"string","description":"The user's timezone."},"email":{"type":"string","description":"The user's email address."},"phoneNumber":{"type":"string","description":"The user's phone number."},"subject":{"type":"string","description":"The subject of the message (for email channels)."}}},"HandleIncomingResponseDto":{"type":"object","properties":{"conversationId":{"type":"string","description":"The ID of the affected conversation."},"messageId":{"type":"string","description":"The ID of the newly created message."},"messages":{"description":"A list of messages generated as a response.","type":"array","items":{"$ref":"#/components/schemas/MessageDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["conversationId","messageId","messages"]},"MessageDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the message."},"sender":{"type":"string","description":"The sender of the message (e.g., user, bot, agent)."},"type":{"type":"string","description":"The type of message (e.g., text, file, template)."},"persona":{"description":"The persona representing the sender.","allOf":[{"$ref":"#/components/schemas/MessagePersonaDto"}]},"providerMessageId":{"type":"string","description":"The message ID from the external provider."},"status":{"type":"string","description":"The delivery status of the message."},"created":{"type":"string","description":"Timestamp when the message was created."},"processed":{"type":"string","description":"Timestamp when the message was processed."},"sent":{"type":"string","description":"Timestamp when the message was sent."},"received":{"type":"string","description":"Timestamp when the message was received by the recipient."},"read":{"type":"string","description":"Timestamp when the message was read by the recipient."},"outgoing":{"type":"boolean","description":"Whether the message is outgoing (true) or incoming (false)."},"messengerId":{"type":"string","description":"The messenger ID associated with the message."},"contextId":{"type":"string","description":"The context ID for message threading."},"content":{"description":"The content of the message.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"tags":{"description":"The list of tags associated with the message.","type":"array","items":{"type":"string"}},"error":{"type":"string","description":"Optional error message."},"isSensitive":{"type":"boolean","description":"Whether the message contains sensitive content."},"streamGroupId":{"type":"string","description":"The stream group ID for grouped streaming messages."},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."}},"required":["id","sender","type","status","created","outgoing","content","tags"]},"MessagePersonaDto":{"type":"object","properties":{"image":{"type":"string","description":"The URL of the persona's avatar image."},"name":{"type":"string","description":"The display name of the persona."}},"required":["image","name"]},"ContentDto":{"type":"object","properties":{"text":{"type":"string","description":"The text content of the message."},"file":{"description":"A file attachment.","allOf":[{"$ref":"#/components/schemas/MessageContentFileDto"}]},"buttons":{"description":"Interactive buttons for the message.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonsDto"}]},"selectedButton":{"description":"The button selected by the user.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonReplyDto"}]},"template":{"description":"A message template.","allOf":[{"$ref":"#/components/schemas/MessageTemplateDto"}]},"location":{"description":"A location shared in the message.","allOf":[{"$ref":"#/components/schemas/MessageLocationDto"}]},"voiceHangup":{"description":"Voice hangup data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceHangupDto"}]},"voiceTransfer":{"description":"Voice transfer data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceTransferDto"}]},"agentHandover":{"description":"Agent handover data.","allOf":[{"$ref":"#/components/schemas/MessageAgentHandoverDto"}]},"email":{"description":"Email content data.","allOf":[{"$ref":"#/components/schemas/MessageContentEmailDto"}]},"textToSpeech":{"description":"Text-to-speech content data.","allOf":[{"$ref":"#/components/schemas/MessageContentTextToSpeechDto"}]},"metaWhatsappTemplate":{"description":"A Meta WhatsApp template message.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplateDto"}]},"operator":{"description":"Operator data for the message.","allOf":[{"$ref":"#/components/schemas/OperatorDto"}]},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."},"leadAiId":{"type":"string","description":"The ID of the Lead AI associated with this message."}}},"MessageContentFileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, audio)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."},"caption":{"type":"string","description":"An optional caption for the file."},"transcript":{"type":"string","description":"The transcript of audio/video content."},"facebookAttachmentId":{"type":"string","description":"The Facebook attachment ID."},"whatsappAttachmentId":{"type":"string","description":"The WhatsApp attachment ID."},"instagramAttachmentId":{"type":"string","description":"The Instagram attachment ID."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageContentButtonsDto":{"type":"object","properties":{"buttons":{"description":"The list of buttons.","type":"array","items":{"$ref":"#/components/schemas/MessageContentButtonDto"}}},"required":["buttons"]},"MessageContentButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, postback)."},"value":{"type":"string","description":"The value associated with the button."},"payload":{"type":"string","description":"An optional payload for the button."}},"required":["label","type","value"]},"MessageContentButtonReplyDto":{"type":"object","properties":{"label":{"type":"string","description":"The label of the selected button."},"value":{"type":"string","description":"The value of the selected button."},"payload":{"type":"string","description":"An optional payload from the button."},"type":{"type":"string","description":"The type of the button."},"reference":{"type":"string","description":"The reference to the original button message."}},"required":["label","value","reference"]},"MessageTemplateDto":{"type":"object","properties":{"body":{"type":"string","description":"The body text of the template."},"header":{"type":"string","description":"The header text of the template."},"footer":{"type":"string","description":"The footer text of the template."}},"required":["body"]},"MessageLocationDto":{"type":"object","properties":{"latitude":{"type":"number","description":"The latitude coordinate."},"longitude":{"type":"number","description":"The longitude coordinate."}},"required":["latitude","longitude"]},"MessageVoiceHangupDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for hanging up the call."},"headers":{"type":"object","description":"Custom SIP headers for the hangup.","additionalProperties":{"type":"string"}}},"required":["reason","headers"]},"MessageVoiceTransferDto":{"type":"object","properties":{"target":{"type":"string","description":"The target phone number or SIP address for the transfer."},"reason":{"type":"string","description":"The reason for the transfer."},"headers":{"type":"object","description":"Custom SIP headers for the transfer.","additionalProperties":{"type":"string"}}},"required":["target","headers"]},"MessageAgentHandoverDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for the handover to an agent."},"timeoutSeconds":{"type":"number","description":"Timeout in seconds before the handover expires."},"agentId":{"type":"string","description":"The ID of the specific agent to hand over to."},"groupId":{"type":"string","description":"The ID of the agent group to hand over to."},"assignmentMethod":{"type":"string","description":"The method for assigning the agent (e.g., round_robin, least_busy)."}},"required":["reason"]},"MessageContentEmailDto":{"type":"object","properties":{"subject":{"type":"string","description":"The subject of the email."},"body":{"type":"string","description":"The body content of the email."},"from":{"type":"string","description":"The sender email address."},"to":{"description":"The list of recipient email addresses.","type":"array","items":{"type":"string"}},"cc":{"description":"The list of CC recipient email addresses.","type":"array","items":{"type":"string"}},"bcc":{"description":"The list of BCC recipient email addresses.","type":"array","items":{"type":"string"}},"attachmentIds":{"description":"The list of attachment IDs.","type":"array","items":{"type":"string"}},"references":{"description":"The list of email references for threading.","type":"array","items":{"type":"string"}}},"required":["subject","body","from","to","cc","bcc","attachmentIds","references"]},"MessageContentTextToSpeechDto":{"type":"object","properties":{"text":{"type":"string","description":"The text to be converted to speech."},"speech":{"type":"string","description":"Pre-generated speech audio reference."}},"required":["text"]},"MessageMetaWhatsAppTemplateDto":{"type":"object","properties":{"templateName":{"type":"string","description":"The name of the template on Meta."},"language":{"type":"string","description":"The language code of the template."},"bodyText":{"type":"string","description":"The body text of the message. Placeholders are in the form `{{1}}`."},"headerText":{"type":"string","description":"The text in the header (if present)."},"footerText":{"type":"string","description":"The text in the footer (if present)."},"header":{"description":"The header component, which can contain a file or text parameters.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_HeaderDto"}]},"bodyParameters":{"description":"A list of values that replace the placeholders in the `bodyText`.","type":"array","items":{"type":"string"}},"buttons":{"description":"A list of buttons attached to the message.","type":"array","items":{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_ButtonDto"}}},"required":["templateName","language","bodyText","bodyParameters","buttons"]},"MessageMetaWhatsAppTemplate_HeaderDto":{"type":"object","properties":{"file":{"description":"The file attached to the header.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_Header_FileDto"}]},"parameters":{"description":"The list of parameter values for the header placeholders.","type":"array","items":{"type":"string"}}},"required":["parameters"]},"MessageMetaWhatsAppTemplate_Header_FileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, video)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageMetaWhatsAppTemplate_ButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, quick_reply)."},"url":{"type":"string","description":"The URL for URL-type buttons."},"value":{"type":"string","description":"The value for quick_reply-type buttons."}},"required":["label","type"]},"OperatorDto":{"type":"object","properties":{"operatorId":{"type":"string","description":"The unique identifier of the operator."}},"required":["operatorId"]}}}}
```

## Processes a step payload.

> \
> \
> \*\*Required Permission:\*\* \`chatbots.step-payload.handle\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation management","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/payload":{"post":{"operationId":"ConversationController_handleIncomingStepPayload[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandleNewIncomingStepPayloadRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandleIncomingResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Processes a step payload.","tags":["Conversation management"],"description":"\n\n**Required Permission:** `chatbots.step-payload.handle`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"HandleNewIncomingStepPayloadRequestDto":{"type":"object","properties":{"chatbotId":{"type":"string","description":"The ID of the chatbot."},"conversationId":{"type":"string","description":"The ID of the conversation."},"flowId":{"type":"string","description":"The ID of the flow to execute."},"stepId":{"type":"string","description":"The ID of the step to execute."},"event":{"type":"string","description":"The event name to trigger."},"eventPayload":{"type":"string","description":"JSON payload for the event."},"async":{"type":"boolean","description":"Whether to process asynchronously."},"isDebug":{"type":"boolean","description":"Whether this is a debug request."}},"required":["chatbotId","conversationId"]},"HandleIncomingResponseDto":{"type":"object","properties":{"conversationId":{"type":"string","description":"The ID of the affected conversation."},"messageId":{"type":"string","description":"The ID of the newly created message."},"messages":{"description":"A list of messages generated as a response.","type":"array","items":{"$ref":"#/components/schemas/MessageDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["conversationId","messageId","messages"]},"MessageDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the message."},"sender":{"type":"string","description":"The sender of the message (e.g., user, bot, agent)."},"type":{"type":"string","description":"The type of message (e.g., text, file, template)."},"persona":{"description":"The persona representing the sender.","allOf":[{"$ref":"#/components/schemas/MessagePersonaDto"}]},"providerMessageId":{"type":"string","description":"The message ID from the external provider."},"status":{"type":"string","description":"The delivery status of the message."},"created":{"type":"string","description":"Timestamp when the message was created."},"processed":{"type":"string","description":"Timestamp when the message was processed."},"sent":{"type":"string","description":"Timestamp when the message was sent."},"received":{"type":"string","description":"Timestamp when the message was received by the recipient."},"read":{"type":"string","description":"Timestamp when the message was read by the recipient."},"outgoing":{"type":"boolean","description":"Whether the message is outgoing (true) or incoming (false)."},"messengerId":{"type":"string","description":"The messenger ID associated with the message."},"contextId":{"type":"string","description":"The context ID for message threading."},"content":{"description":"The content of the message.","allOf":[{"$ref":"#/components/schemas/ContentDto"}]},"tags":{"description":"The list of tags associated with the message.","type":"array","items":{"type":"string"}},"error":{"type":"string","description":"Optional error message."},"isSensitive":{"type":"boolean","description":"Whether the message contains sensitive content."},"streamGroupId":{"type":"string","description":"The stream group ID for grouped streaming messages."},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."}},"required":["id","sender","type","status","created","outgoing","content","tags"]},"MessagePersonaDto":{"type":"object","properties":{"image":{"type":"string","description":"The URL of the persona's avatar image."},"name":{"type":"string","description":"The display name of the persona."}},"required":["image","name"]},"ContentDto":{"type":"object","properties":{"text":{"type":"string","description":"The text content of the message."},"file":{"description":"A file attachment.","allOf":[{"$ref":"#/components/schemas/MessageContentFileDto"}]},"buttons":{"description":"Interactive buttons for the message.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonsDto"}]},"selectedButton":{"description":"The button selected by the user.","allOf":[{"$ref":"#/components/schemas/MessageContentButtonReplyDto"}]},"template":{"description":"A message template.","allOf":[{"$ref":"#/components/schemas/MessageTemplateDto"}]},"location":{"description":"A location shared in the message.","allOf":[{"$ref":"#/components/schemas/MessageLocationDto"}]},"voiceHangup":{"description":"Voice hangup data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceHangupDto"}]},"voiceTransfer":{"description":"Voice transfer data.","allOf":[{"$ref":"#/components/schemas/MessageVoiceTransferDto"}]},"agentHandover":{"description":"Agent handover data.","allOf":[{"$ref":"#/components/schemas/MessageAgentHandoverDto"}]},"email":{"description":"Email content data.","allOf":[{"$ref":"#/components/schemas/MessageContentEmailDto"}]},"textToSpeech":{"description":"Text-to-speech content data.","allOf":[{"$ref":"#/components/schemas/MessageContentTextToSpeechDto"}]},"metaWhatsappTemplate":{"description":"A Meta WhatsApp template message.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplateDto"}]},"operator":{"description":"Operator data for the message.","allOf":[{"$ref":"#/components/schemas/OperatorDto"}]},"delay":{"type":"number","description":"Delay in milliseconds before sending the message."},"leadAiId":{"type":"string","description":"The ID of the Lead AI associated with this message."}}},"MessageContentFileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, audio)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."},"caption":{"type":"string","description":"An optional caption for the file."},"transcript":{"type":"string","description":"The transcript of audio/video content."},"facebookAttachmentId":{"type":"string","description":"The Facebook attachment ID."},"whatsappAttachmentId":{"type":"string","description":"The WhatsApp attachment ID."},"instagramAttachmentId":{"type":"string","description":"The Instagram attachment ID."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageContentButtonsDto":{"type":"object","properties":{"buttons":{"description":"The list of buttons.","type":"array","items":{"$ref":"#/components/schemas/MessageContentButtonDto"}}},"required":["buttons"]},"MessageContentButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, postback)."},"value":{"type":"string","description":"The value associated with the button."},"payload":{"type":"string","description":"An optional payload for the button."}},"required":["label","type","value"]},"MessageContentButtonReplyDto":{"type":"object","properties":{"label":{"type":"string","description":"The label of the selected button."},"value":{"type":"string","description":"The value of the selected button."},"payload":{"type":"string","description":"An optional payload from the button."},"type":{"type":"string","description":"The type of the button."},"reference":{"type":"string","description":"The reference to the original button message."}},"required":["label","value","reference"]},"MessageTemplateDto":{"type":"object","properties":{"body":{"type":"string","description":"The body text of the template."},"header":{"type":"string","description":"The header text of the template."},"footer":{"type":"string","description":"The footer text of the template."}},"required":["body"]},"MessageLocationDto":{"type":"object","properties":{"latitude":{"type":"number","description":"The latitude coordinate."},"longitude":{"type":"number","description":"The longitude coordinate."}},"required":["latitude","longitude"]},"MessageVoiceHangupDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for hanging up the call."},"headers":{"type":"object","description":"Custom SIP headers for the hangup.","additionalProperties":{"type":"string"}}},"required":["reason","headers"]},"MessageVoiceTransferDto":{"type":"object","properties":{"target":{"type":"string","description":"The target phone number or SIP address for the transfer."},"reason":{"type":"string","description":"The reason for the transfer."},"headers":{"type":"object","description":"Custom SIP headers for the transfer.","additionalProperties":{"type":"string"}}},"required":["target","headers"]},"MessageAgentHandoverDto":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for the handover to an agent."},"timeoutSeconds":{"type":"number","description":"Timeout in seconds before the handover expires."},"agentId":{"type":"string","description":"The ID of the specific agent to hand over to."},"groupId":{"type":"string","description":"The ID of the agent group to hand over to."},"assignmentMethod":{"type":"string","description":"The method for assigning the agent (e.g., round_robin, least_busy)."}},"required":["reason"]},"MessageContentEmailDto":{"type":"object","properties":{"subject":{"type":"string","description":"The subject of the email."},"body":{"type":"string","description":"The body content of the email."},"from":{"type":"string","description":"The sender email address."},"to":{"description":"The list of recipient email addresses.","type":"array","items":{"type":"string"}},"cc":{"description":"The list of CC recipient email addresses.","type":"array","items":{"type":"string"}},"bcc":{"description":"The list of BCC recipient email addresses.","type":"array","items":{"type":"string"}},"attachmentIds":{"description":"The list of attachment IDs.","type":"array","items":{"type":"string"}},"references":{"description":"The list of email references for threading.","type":"array","items":{"type":"string"}}},"required":["subject","body","from","to","cc","bcc","attachmentIds","references"]},"MessageContentTextToSpeechDto":{"type":"object","properties":{"text":{"type":"string","description":"The text to be converted to speech."},"speech":{"type":"string","description":"Pre-generated speech audio reference."}},"required":["text"]},"MessageMetaWhatsAppTemplateDto":{"type":"object","properties":{"templateName":{"type":"string","description":"The name of the template on Meta."},"language":{"type":"string","description":"The language code of the template."},"bodyText":{"type":"string","description":"The body text of the message. Placeholders are in the form `{{1}}`."},"headerText":{"type":"string","description":"The text in the header (if present)."},"footerText":{"type":"string","description":"The text in the footer (if present)."},"header":{"description":"The header component, which can contain a file or text parameters.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_HeaderDto"}]},"bodyParameters":{"description":"A list of values that replace the placeholders in the `bodyText`.","type":"array","items":{"type":"string"}},"buttons":{"description":"A list of buttons attached to the message.","type":"array","items":{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_ButtonDto"}}},"required":["templateName","language","bodyText","bodyParameters","buttons"]},"MessageMetaWhatsAppTemplate_HeaderDto":{"type":"object","properties":{"file":{"description":"The file attached to the header.","allOf":[{"$ref":"#/components/schemas/MessageMetaWhatsAppTemplate_Header_FileDto"}]},"parameters":{"description":"The list of parameter values for the header placeholders.","type":"array","items":{"type":"string"}}},"required":["parameters"]},"MessageMetaWhatsAppTemplate_Header_FileDto":{"type":"object","properties":{"name":{"type":"string","description":"The file name."},"url":{"type":"string","description":"The URL where the file is hosted."},"type":{"type":"string","description":"The type of file (e.g., image, document, video)."},"mimeType":{"type":"string","description":"The MIME type of the file."},"size":{"type":"number","description":"The file size in bytes."},"attachmentRef":{"type":"string","description":"The reference ID for the attachment."}},"required":["name","url","type","mimeType","size","attachmentRef"]},"MessageMetaWhatsAppTemplate_ButtonDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the button."},"type":{"type":"string","description":"The type of button (e.g., url, quick_reply)."},"url":{"type":"string","description":"The URL for URL-type buttons."},"value":{"type":"string","description":"The value for quick_reply-type buttons."}},"required":["label","type"]},"OperatorDto":{"type":"object","properties":{"operatorId":{"type":"string","description":"The unique identifier of the operator."}},"required":["operatorId"]}}}}
```

## Triggers a custom event in a conversation

> \
> \
> \*\*Required Permission:\*\* \`chatbots.events.handle\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation management","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/custom-event":{"post":{"operationId":"ConversationController_triggerCustomConversationEvent[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerCustomConversationEventRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerCustomConversationEventResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Triggers a custom event in a conversation","tags":["Conversation management"],"description":"\n\n**Required Permission:** `chatbots.events.handle`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"TriggerCustomConversationEventRequestDto":{"type":"object","properties":{"chatbotId":{"type":"string","description":"The ID of the chatbot."},"conversationId":{"type":"string","description":"The ID of the conversation."},"event":{"type":"string","description":"The custom event name to trigger."}},"required":["chatbotId","conversationId","event"]},"TriggerCustomConversationEventResponseDto":{"type":"object","properties":{"error":{"type":"string","description":"Optional error message."}}}}}}
```


---

# 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-management.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.