Messaging

Sending is the standard sendMessage mutation - the same one the dashboard calls. There is no separate machine-only send path, and no reduced message-type subset: a key can send anything an operator can.

Scope: MESSAGES_SEND for everything on this page. Posting an internal note additionally needs NOTES_WRITE.

sendMessage

sendMessage(chatId: String!, input: CreateCombinedMessageInput!): Message!

Sends a message into an existing chat thread.

Arguments

CreateCombinedMessageInput - the fields that matter for an integration:

Returns Message!

Rules

• On WhatsApp, free-form text only works inside the 24-hour customer-service window. Outside it, send an approved template with sendWhatsAppTemplateMessage. Instagram has its own window.
• media entries are either media IDs belonging to the acting org, or public https:// URLs. A media ID from another org is 403; a URL that fails the SSRF check is 400 (see media by URL).
• replyToMessage must point to a message in the same chat.

Example - text

mutation Send {
  sendMessage(chatId: "6804f4c2a6f9f35f6e66f1a1", input: {
    text: "Your pizza is on the way 🍕"
  }) {
    _id
    deliveryStatus
    createdAt
  }
}

{
  "data": {
    "sendMessage": {
      "_id": "6804f5011c34d0012ab8a077",
      "deliveryStatus": "SENT",
      "createdAt": "2026-10-01T18:00:00.000Z"
    }
  }
}

Example - an album with a caption

mutation SendAlbum {
  sendMessage(chatId: "6804f4c2a6f9f35f6e66f1a1", input: {
    isMediaGroup: true
    mediaGroup: ["6805b1a0…", "6805b1a1…", "6805b1a2…"]
    caption: "Tonight's specials"
    showCaptionAboveMedia: true
  }) { _id type deliveryStatus }
}

Example - an internal note

mutation Note {
  sendMessage(chatId: "6804f4c2a6f9f35f6e66f1a1", input: {
    internal: true
    text: "Customer called twice about this order - escalating."
  }) { _id }
}

Requires NOTES_WRITE. The note never reaches the customer and is invisible to keys without that scope.

Sending as an Operator

By default a key's message is authored by the organisation that owns the key. Pass actingUserId to author it as a named operator instead.

For a tech-provider key acting on a managed client, that default author is the provider, not the client - which is what a white-label integration usually wants.

It works on sendMessage and on conversation notes.

Async Send

A normal sendMessage waits for the channel provider. With async: true the call returns as soon as the message is stored, and the outcome arrives later as a webhook.

Keys only - a member passing async gets a 400. Internal notes and mentions ignore it and are answered synchronously.

The Flow

1. Call sendMessage with async: true.
2. Wexio validates and stores the message, bills it once, and returns immediately with deliveryStatus: PENDING and no provider id.
3. message.outbound.created fires with PENDING.
4. The provider send runs in the background, in creation order per chat.
5. message.outbound.status fires once with the outcome - SENT (or DELIVERED/READ on channels without receipts) with the provider id, or FAILED with an error.

When to Use It

Use async: true for bulk sends and anywhere you do not want to hold a request open on a slow channel. Keep the synchronous form when your own code needs the provider id in the same call.

Over Capacity

If the async backlog is full, the call returns RATE_LIMITED with retryAfterMs and nothing is stored - so a retry cannot duplicate the message. See Rate limits.

updateMessage

updateMessage(messageId: String!, input: UpdateMessageInput!): Message!

Edits a message you already sent.

Arguments

UpdateMessageInput

Returns Message! - the updated message.

Whether the edit propagates to the customer depends on the channel: some support editing a delivered message, others only change Wexio's copy.

deleteMessage

deleteMessage(messageId: String!): Boolean!

Deletes a message. Returns true on success.

Emits message.inbound.deleted or message.outbound.deleted to your webhook.

Reactions

addMessageReaction(messageId: String!, emoji: String!): Message
removeMessageReaction(messageId: String!, emoji: String!): Message

Add or remove an emoji reaction. Both return the updated Message, or null if there was nothing to change.

mutation React {
  addMessageReaction(messageId: "6804f4f01c34d0012ab8a055", emoji: "👍") { _id }
}

Reaction support is channel-dependent.

Media

Two ways to get media into a message: upload it, or hand Wexio a URL to fetch. Media IDs are scoped to the org they were uploaded into.

Media by URL

Put a public https:// URL straight into media and Wexio fetches, stores and sends it - no upload round-trip:

mutation SendByUrl {
  sendMessage(chatId: "6804f4c2a6f9f35f6e66f1a1", input: {
    media: ["https://cdn.example.com/menu.png?v=2"]
    caption: "Tonight's menu"
  }) { _id deliveryStatus }
}

A URL that is fetched becomes a normal media record in the org, so the message you get back carries a real media ID.

Uploading

createMedia(createMediaInput: CreateMediaInput!, file: Upload!): Media!
uploadMultipleMedia(files: [Upload!]!, createMediaInputs: [CreateMediaInput!]!): [Media!]!
deleteMedia(id: String!): Boolean!

Take _id from the returned Media and pass it in sendMessage's media or mediaGroup.

sendWhatsAppTemplateMessage

sendWhatsAppTemplateMessage(input: SendWhatsAppTemplateInput!): SendWhatsAppTemplateResult!

Sends an approved WhatsApp template. This is the path for reaching a customer outside the 24-hour window, and the only way to open a WhatsApp conversation from a phone number.

Read the available templates with whatsAppTemplates - that needs CHANNELS_MANAGE, while sending needs MESSAGES_SEND.

A Template Send Lands in Two Steps

The message is stored before it is rendered, so it exists in reads straight away:

See Channel constraints for which channels can start a conversation at all.