# Inbox messages

## Sends a new message on behalf of an agent

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox messages","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/inbox/{chatbotId}/messages":{"post":{"operationId":"InboxMessageController_sendMessage[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/SendMessageRequestDto"}}}},"responses":{"201":{"description":"Message sent successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Sends a new message on behalf of an agent","tags":["Inbox messages"],"description":"\n\n**Required Permission:** `chatbots.inbox.messages.send`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"SendMessageRequestDto":{"type":"object","properties":{"conversationId":{"type":"string","description":"The ID of the conversation in which the message is sent."},"text":{"type":"string","description":"The text content of the message. Either `text` or `attachmentRef` must be present."},"attachmentRef":{"type":"string","description":"The reference to an uploaded attachment. Either `text` or `attachmentRef` must be present."}},"required":["conversationId"]},"SendMessageResponseDto":{"type":"object","properties":{"message":{"description":"The newly created message.","nullable":true,"allOf":[{"$ref":"#/components/schemas/MessageDto"}]},"error":{"type":"string","description":"Optional error message."}},"required":["message"]},"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"]}}}}
```


---

# 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/inbox-messages.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.