v51

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-014102371.0 MB

Case

Send a message from a case

Send a message from a known, open case with an explicit source and destination address (design §4.5). Validation order:

Case validation -- case belongs to the calling customer and is status=open (closed cases must be reopened via POST /v1.0/contact_cases/{id}/continue first).
Destination-to-case binding -- destination must be attributable to this specific case (matched Contact's addresses, or the case's bare peer_target when unresolved). Failure of either sub-check returns the same generic error, by design, to prevent a caller from using case_id as a bare capability token to probe which binding sub-case failed.
Source-ownership validation -- source must be an active, normal number owned by this case's customer. The message is sent through the same underlying conversation-message send path as POST /v1.0/service_agents/conversations/{id}/messages, reusing the ConversationManagerMessage response schema.

post/contact_cases/{id}/messages

Path parameters

idstring uuid required

Example:550e8400-e29b-41d4-a716-446655440000

The ID of the case. The ID is returned from GET /v1.0/contact_cases response.

Request body

sourcestring required

The business's own number to send from. Must be an active, normal number owned by this case's customer.

destinationstring required

The customer's number to send to. Must be attributable to this case (the matched Contact's address, or the case's peer_target).

textstring required

The text content of the message.

Example request

{
  "source": "+15551234567",
  "destination": "+15559876543",
  "text": "Thanks for reaching out -- following up on your request."
}

Response

The details of the sent message.

idstring uuid

The unique identifier of the message.

customer_idstring uuid

The unique identifier of the customer. Returned from the GET /customers response.

conversation_idstring uuid

The unique identifier of the conversation. Returned from the GET /conversations response.

direction'outgoing' | 'incoming'

Direction of the message (incoming or outgoing).

status'progressing' | 'done' | 'failed'

Delivery status of the message.

reference_type'' | 'message' | 'line' | 'whatsapp' | 'email'

Source channel that produced the message.

reference_idstring uuid

The unique identifier of the referenced resource. The actual resource type is determined by reference_type. Returned from the corresponding resource endpoint.

textstring

The message content.

tm_createstring date-time

Timestamp when the message was created.

tm_updatestring date-time

Timestamp when the message was last updated.

tm_deletestring date-time

Timestamp when the message was deleted.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "direction": "incoming",
  "status": "done",
  "reference_type": "message",
  "reference_id": "f6a7b8c9-d0e1-2345-6789-0abcdef01234",
  "source": {
    "type": "tel",
    "target": "+14155551234",
    "target_name": "John Smith",
    "name": "Main Office",
    "detail": "Primary contact number"
  },
  "destination": {
    "type": "tel",
    "target": "+14155551234",
    "target_name": "John Smith",
    "name": "Main Office",
    "detail": "Primary contact number"
  },
  "text": "Hello, how can I help you today?",
  "medias": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
      "type": "image",
      "filename": "photo_2026-01-15.jpg",
      "tm_create": "2026-01-15T09:30:00.000000Z",
      "tm_update": "2026-01-15T09:30:00.000000Z",
      "tm_delete": "2026-01-15T09:30:00.000000Z"
    }
  ],
  "tm_create": "2026-01-15T09:30:00.000000Z",
  "tm_update": "2026-01-15T09:30:00.000000Z",
  "tm_delete": "2026-01-15T09:30:00.000000Z"
}