# Send an agent message (v2)

Send an agent reply on any channel through a single endpoint. The target channel is set via the channel field (WHATSAPP, WEB, or FACEBOOK) and routing is handled server-side — replacing the per-channel v1 send endpoints. For a text message set text; for media, first upload the file via Upload media for an agent message and send the returned mediaUrl (the content type defaults to MEDIA when a mediaUrl is present). The agent is resolved from your API key / session and the participant is tenant-checked.

Endpoint: POST /pl4chat-service/api/v2/messages
Version: 3.0.0
Security: apikeyAuth

## Request fields (application/json):

  - `participantId` (string, required)
    Chat participant to send to.
    Example: "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890"

  - `channel` (string, required)
    Channel to route the message on.
    Enum: "WHATSAPP", "WEB", "FACEBOOK"

  - `tempId` (string)
    Optional. Client-generated id echoed back on the response to correlate an optimistic UI message. Omit it if you don't need correlation.
    Example: "c9f0b308-1a0d-3f3f-7912-464f06677c6b"

  - `text` (string)
    Message text, or the caption for a media send.
    Example: "Thanks for reaching out — how can I help?"

  - `contentType` (string)
    Optional. Defaults to TEXT, or MEDIA when a mediaUrl is present.
    Enum: "TEXT", "MEDIA"

  - `mediaUrl` (string)
    Hosted media URL from the media upload endpoint. Its presence makes this a media send.
    Example: "https://cdn.example.com/uploads/quote-1234.pdf"

  - `mediaType` (string)
    Media kind (from the upload response).
    Enum: "DOCUMENT", "IMAGE", "VIDEO", "NULL", "BUTTON", "FILE", "AUDIO", "VOICE"

  - `quotedExternalMessageId` (string)
    WhatsApp id of a message being quoted/replied to.
    Example: "3EB0123456789ABCDEF0"

  - `quotedText` (string)
    Snapshot of the quoted message's text.
    Example: "Hi, is this about order #1234?"

## Response 200 fields (application/json):

  - `id` (string)
    Example: "c9d01234-e5f6-a7b8-c9d0-1234e5f6a7b8"

  - `tempId` (string)
    Temporary client-generated id used to correlate a send request with its response. Present only when the sender supplied one.
    Example: "c9f0b308-1a0d-3f3f-7912-464f06677c6b"

  - `sequenceNumber` (integer)
    Monotonic ordering hint within the conversation.
    Example: 42

  - `direction` (string)
    Enum: "OUTGOING", "INCOMING"

  - `contentType` (string)
    Enum: "BUTTON", "CAROUSEL", "DROPDOWN", "IMAGE", "TEXT", "DATE", "FILE", "MEDIA", "LOCATION", "RATING"

  - `channel` (string)
    Enum: same as `channel` (3 values)

  - `text` (string)
    Example: "Hello, I need help with my account."

  - `createdTime` (string)
    Example: "2026-01-15T10:30:00Z"

  - `userOriginated` (boolean)
    true when a human typed the message (agent or customer); false for bot-generated messages.
    Example: true

  - `messageOwner` (string)
    Enum: "agent", "customer", "system"

  - `sender` (string)
    Address the message was sent from (e.g. the customer's phone number for inbound, the business number for outbound).
    Example: "+27987654321"

  - `receiver` (string)
    Address the message was delivered to.
    Example: "+27123456789"

  - `ctId` (string)
    Custom tracking id for the message, if one was supplied on send.
    Example: "order-1234-confirm"

  - `sent` (boolean)
    Example: true

  - `delivered` (boolean)
    Example: true

  - `read` (boolean)

  - `played` (boolean)
    True when a voice note was played (listened to) by the recipient.

  - `sentTime` (string)
    Example: "2026-01-15T10:30:01Z"

  - `deliveredTime` (string)
    Example: "2026-01-15T10:30:05Z"

  - `readTime` (string)
    Example: "2026-01-15T10:31:00Z"

  - `playedTime` (string)
    Timestamp the voice note was played.
    Example: "2026-01-15T10:31:30Z"

  - `mediaURL` (string)
    Example: "https://example.com/media/photo.jpg"

  - `fileExtension` (string)
    File extension of the attached media, when present.
    Example: "jpg"

  - `mediaType` (string)
    Enum: same as `mediaType` (8 values)

  - `latitude` (string)
    Example: "-26.2041"

  - `longitude` (string)
    Example: "28.0473"

  - `address` (string)
    Example: "123 Main St, Johannesburg"

  - `label` (string)
    Example: "Head Office"

  - `agent` (object)
    Lean reference to the agent who sent or owns a message.

  - `agent.id` (string)
    Example: "b2c3d4e5-f6a7-8901-b2c3-d4e5f6a78901"

  - `agent.firstName` (string)
    Example: "Alice"

  - `agent.lastName` (string)
    Example: "Smith"

  - `agent.email` (string)
    Example: "alice.smith@example.com"

  - `agent.avatar` (string)
    URL of the agent's avatar image.
    Example: "https://example.com/avatars/alice.png"

  - `reaction` (object)

  - `reaction.reactorName` (string)
    Example: "John Doe"

  - `reaction.reactorNumber` (string)
    Example: "+27821234567"

  - `reaction.reactionEmoji` (string)
    Example: "👍"

  - `whatsAppMessageId` (string)
    Provider (WhatsApp) message id.
    Example: "3EB09839C39C57F54A9EC5"

  - `facebookMessageId` (string)
    Provider (Facebook) message id.
    Example: "m_AbCdEf123456"

  - `quotedExternalMessageId` (string)
    WhatsApp id of the message this one replies to/quotes (present when the message is a reply).
    Example: "3EB0123456789ABCDEF0"

  - `quotedText` (string)
    Snapshot of the quoted message's text, captured at reply time.
    Example: "Hi, is this about order #1234?"

## Response 400 fields (application/json):

  - `status` (string)
    Example: "ERROR"

  - `message` (string)
    Example: "Invalid Parameters"

  - `requestId` (string)
    Example: "c3a1f8e2-4b6d-11ee-be56-0242ac120002"

  - `timestamp` (string)
    Example: "2026-01-15T10:30:00Z"

## Response 401 fields (application/json):

  - `status` (string)
    Example: "ERROR"

  - `message` (string)
    Example: "Unauthorized user"

  - `requestId` (string)
    Example: "c3a1f8e2-4b6d-11ee-be56-0242ac120002"

  - `timestamp` (string)
    Example: "2026-01-15T10:30:00Z"

## Response 403 fields (application/json):

  - `status` (string)
    Example: "ERROR"

  - `message` (string)
    Example: "Forbidden"

  - `requestId` (string)
    Example: "c3a1f8e2-4b6d-11ee-be56-0242ac120002"

  - `timestamp` (string)
    Example: "2026-01-15T10:30:00Z"

## Response 404 fields (application/json):

  - `status` (string)
    Example: "ERROR"

  - `message` (string)
    Example: "Resource not found"

  - `requestId` (string)
    Example: "c3a1f8e2-4b6d-11ee-be56-0242ac120002"

  - `timestamp` (string)
    Example: "2026-01-15T10:30:00Z"