Inbox Messages

Sends a new message on behalf of an agent

post

Required Permission: chatbots.inbox.messages.send

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

conversationIdstringRequired

The ID of the conversation in which the message is sent.

Example: N1HSdvJSxAZmmcyVz5HW

textstringOptional

The text content of the message. Either text or attachmentRef must be present.

Example: Hello, I have a question.

attachmentRefstringOptional

The reference to an uploaded attachment. Either text or attachmentRef must be present.

Example: z5AV6Eu3aBBdbu4sdjEa

Responses

201

Message sent successfully.

application/json

errorstringOptional

Optional error message.

400

Invalid input data.

403

Insufficient permissions.

post/v1/inbox/{chatbotId}/messages

POST /v1/inbox/{chatbotId}/messages HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 115

{
  "conversationId": "N1HSdvJSxAZmmcyVz5HW",
  "text": "Hello, I have a question.",
  "attachmentRef": "z5AV6Eu3aBBdbu4sdjEa"
}

{
  "message": {
    "id": "msg_abc123xyz",
    "sender": "bot",
    "type": "text",
    "persona": {
      "image": "https://storage.example.com/avatars/support.png",
      "name": "Support Bot"
    },
    "providerMessageId": "wamid.HBgNNDkxNTEyNjAyNTQ1Ng==",
    "status": "delivered",
    "created": "2025-10-06T12:00:00Z",
    "processed": "2025-10-06T12:00:01Z",
    "sent": "2025-10-06T12:00:02Z",
    "received": "2025-10-06T12:00:03Z",
    "read": "2025-10-06T12:00:10Z",
    "outgoing": true,
    "messengerId": "messenger_abc123",
    "contextId": "ctx_xyz789",
    "content": {
      "text": "text",
      "file": {
        "name": "text",
        "url": "text",
        "type": "text",
        "mimeType": "text",
        "size": 1,
        "attachmentRef": "text",
        "caption": "text",
        "transcript": "text"
      },
      "buttons": {
        "buttons": [
          {
            "label": "text",
            "type": "text",
            "value": "text",
            "payload": "text"
          }
        ]
      },
      "selectedButton": {
        "label": "text",
        "value": "text",
        "payload": "text",
        "type": "text",
        "reference": "text"
      },
      "template": {
        "body": "text",
        "header": "text",
        "footer": "text"
      },
      "contact": {
        "addresses": [
          {
            "city": "text",
            "country": "text",
            "countryCode": "text",
            "street": "text",
            "type": "text",
            "zip": "text"
          }
        ],
        "emails": [
          {
            "email": "[e-mail]",
            "type": "text"
          }
        ],
        "name": {
          "firstName": "text",
          "formattedName": "text",
          "lastName": "text"
        },
        "org": {
          "company": "text",
          "title": "text"
        },
        "phones": [
          {
            "phone": "text",
            "type": "text",
            "waId": "text"
          }
        ]
      },
      "location": {
        "latitude": 1,
        "longitude": 1
      },
      "note": {
        "text": "text",
        "mentions": [
          "text"
        ]
      },
      "voiceHangup": {
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "voiceTransfer": {
        "target": "text",
        "reason": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "agentHandover": {
        "reason": "text",
        "timeoutSeconds": 1,
        "agentId": "text",
        "groupId": "text",
        "assignmentMethod": "text"
      },
      "email": {
        "subject": "text",
        "body": "text",
        "from": "text",
        "to": [
          "text"
        ],
        "cc": [
          "text"
        ],
        "bcc": [
          "text"
        ],
        "attachmentIds": [
          "text"
        ],
        "references": [
          "text"
        ],
        "attachments": [
          {
            "id": "att_123",
            "name": "invoice.pdf",
            "created": "2024-01-01T00:00:00Z",
            "updated": "2024-01-01T00:00:00Z",
            "size": 102400,
            "contentType": "application/pdf",
            "selfLink": "bucketId-objectId/filename.filetype",
            "metadata": {
              "source": "email"
            }
          }
        ]
      },
      "transcription": {
        "text": "text",
        "language": "text",
        "audioRef": "text"
      },
      "textToSpeech": {
        "text": "text",
        "speech": "text"
      },
      "reaction": {
        "reactionToMid": "text",
        "action": "text",
        "reaction": "text",
        "emoji": "text"
      },
      "callSettings": {
        "userInputSpeechDetectionTimeout": 1,
        "dtmf": true,
        "bargeIn": true
      },
      "metaWhatsappTemplate": {
        "templateName": "order_shipped_notification",
        "language": "DE",
        "bodyText": "Your order {{1}} has been shipped.",
        "headerText": "text",
        "footerText": "text",
        "header": {
          "file": {
            "name": "header_image.png",
            "url": "https://storage.example.com/files/header.png",
            "type": "image",
            "mimeType": "image/png",
            "size": 51200,
            "attachmentRef": "att_header123"
          },
          "parameters": [
            "Order #12345"
          ]
        },
        "bodyParameters": [
          "#12345"
        ],
        "buttons": [
          {
            "label": "Track Order",
            "type": "URL",
            "url": "https://example.com/track/{{1}}",
            "value": "track_order"
          }
        ]
      },
      "operator": {
        "operatorId": "op_abc123xyz"
      },
      "delay": 1,
      "leadAiId": "text"
    },
    "tags": [
      "important",
      "follow-up"
    ],
    "error": "text",
    "isSensitive": false,
    "streamGroupId": "stream_abc123",
    "delay": 1000
  },
  "error": "text"
}