Messages

Send outbound WhatsApp message

Send an outbound WhatsApp message from one of your phone numbers to any recipient.

Conversation handling:

  • If no active conversation exists, a new target and conversation are created automatically.
  • If an active conversation exists in the same campaign, returns 409 ACTIVE_CONVERSATION_EXISTS with conflictData.existingConversationId. Re-send with force: true to append the message to that conversation.
  • If an active conversation exists in a different campaign, returns 409 DIFFERENT_CAMPAIGN_CONFLICT. This is a hard block — force: true will not bypass it.

Provider rules:

  • ainumber (Meta): Use type: "template" to initiate a new conversation or when outside the 24h window. Use type: "text" only when an active conversation with a recent inbound message exists.
  • 2chat: Always supports type: "text". Templates are not supported.

Use GET /api/v1/phone-numbers/{phoneId}/whatsapp/templates to list available templates for a phone number.

post/api/v1/messages/outbound

Request

  • Base URL: http://localhost:8080
  • URL: http://localhost:8080/api/v1/messages/outbound
  • Auth: bearerAuth (a scheme the document does not define)

Request body

phoneIdstring uuid required

UUID of the PhoneNumber record to send from

tostring required

Recipient phone number (E.164 format recommended)

campaignIdstring uuid required

Campaign UUID to associate the contact with

agentIdstring uuid

UUID of the Agent to associate with this conversation. When provided, takes precedence over the automatic agent lookup. Strongly recommended for new conversations.

forceboolean

Skip the active-conversation conflict check. Set to true after the user has confirmed they want to send to an existing conversation.

Example request

{
  "phoneId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to": "+5215512345678",
  "campaignId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "agentId": "c3d4e5f6-a7b8-9012-cdef-234567890123",
  "message": {
    "language": "es",
    "variables": {
      "1": "Juan",
      "2": "PROMO50"
    },
    "headerMedia": "https://cdn.example.com/menu.jpg"
  }
}

Response

Created

successtrue required
messagestring

Example response

{
  "data": {
    "messageId": "msg_abc123",
    "conversationId": "conv_xyz789",
    "status": "queued",
    "provider": "ainumber",
    "conversationCreated": true
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.