Skip to main content

​
Overview

Sends a message from the authenticated agent into a conversation. The message is delivered to the customer via the conversation’s channel adapter (e.g. live chat widget, WhatsApp, email). SLA first-response time is recorded on the first agent message.
Your plan’s monthly message limit applies. If you exceed your plan’s max_messages_per_month, this endpoint returns an error. Upgrade your plan to increase the limit.

​
Request

Method: POST URL: /api/v1/conversations/{conversation_id}/messages

​
Headers

HeaderValue
AuthorizationBearer
Content-Typeapplication/json

​
Path parameters

​
conversation_id
string (UUID)
required
The UUID of the conversation to send a message in.

​
Body parameters

​
content
string
required
The text content of the message.
​
attachments
array
Optional list of attachment objects. Upload files first using POST /api/v1/conversations/{conversation_id}/upload to obtain URLs, then reference them here. Defaults to an empty array.

​
Response

Returns the created message object.
​
id
string (UUID)
Unique identifier for the message.
​
conversation_id
string (UUID)
The conversation this message belongs to.
​
sender_type
string
Always "agent" for messages sent via this endpoint.
​
sender_id
string (UUID) | null
UUID of the authenticated agent who sent the message.
​
content
string
The text content of the message.
​
attachments
array
List of attachment objects included with the message.
​
created_at
string (ISO 8601)
Timestamp when the message was sent.

​
Example

curl -X POST https://api.pingback.live/api/v1/conversations/c3d4e5f6-a7b8-9012-cdef-123456789012/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Thanks for reaching out! I can help you with that.",
    "attachments": []
  }'

const conversationId = 'c3d4e5f6-a7b8-9012-cdef-123456789012';
const response = await fetch(
  `https://api.pingback.live/api/v1/conversations/${conversationId}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content: 'Thanks for reaching out! I can help you with that.',
      attachments: [],
    }),
  }
);
const message = await response.json();

​
Response example

{
  "id": "g7b8c9d0-e1f2-3456-abcd-567890123456",
  "conversation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "sender_type": "agent",
  "sender_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": "Thanks for reaching out! I can help you with that.",
  "attachments": [],
  "created_at": "2024-03-01T09:05:00Z"
}

​
Errors

StatusMeaning
401Unauthorized — missing or invalid Bearer token
403Plan message limit reached for this month
404Conversation not found or does not belong to your business
422Validation error — content is required