SubizDeveloper Docs
Conversations & Messages

API 4.0

Send to a customer

Send a message to a customer through a connected channel.

POSThttps://api.subiz.com.vn/4.0/accounts/{accid}/users/{uid}/messages

Use this endpoint to message a customer through a channel identity, such as a Facebook or Zalo profile. You do not need a conversation ID. If you already have one, Send to a conversation is simpler.

Before you send

  • Get a Bearer access token and your account ID.
  • Know the customer’s channel identity: channel, source, and profile ID from your connected integration.
  • Use a test customer while developing. Each successful request sends a real message.

Identify the customer

Choose one of two options:

  • Subiz user ID. Put the customer’s ID in the uid path segment.
  • Channel identity. Set channel, channel_source, and profile_id at the top level of the body. Subiz finds the customer with that identity, or creates one, and uses that customer instead of the path uid.

Both channel and profile_id are needed for the second option. Otherwise the path uid is used.

Request body

Field Type Description
accid (path) string Your account ID.
uid (path) string Customer ID. Ignored when the channel identity is set.
channel string Optional. Channel of the identity, such as facebook or zalo.
channel_source string Optional. Connected page or account, such as a Facebook page ID.
profile_id string Optional. Customer’s ID on that channel.
messages array Message events to try, in order. Up to five.
messages[].type string Use message_sent.
messages[].touchpoint object Where to deliver: channel, source, and id.
messages[].data.message object Message content. See Message formats.

A touchpoint describes one destination:

{
  "channel": "facebook",
  "source": "page_example",
  "id": "profile_example"
}

source is the connected page or account. The meaning of id depends on the channel; it is usually the customer’s profile ID there. Use values from your integration, not the Subiz user ID.

Fallback destinations

messages is a list of alternatives, not a batch. Subiz tries each item in order and stops after the first successful send. Use this to fall back to another channel, for example Zalo when Facebook fails.

To reach one destination, send one item. With an agent’s token, arrays longer than five are rejected, and every item counts toward the message sending limits, even if it is never sent.

Subiz can stop early if the customer has unsubscribed from the channel.

Response

A successful request returns HTTP 200 with one event: the message that was sent. It does not list results for the other items. Selected fields:

{
  "id": "event_example",
  "account_id": "account_example",
  "type": "message_sent",
  "created": 1763107200000,
  "data": {
    "message": {
      "format": "plaintext",
      "text": "Hello! How can we help?"
    }
  }
}

A 200 response does not confirm delivery by the external channel.

Errors and retries

Check the HTTP status before reading the body. The send can also be rejected by the channel, for example when the integration is disconnected or the channel does not allow the message. See Errors.

Do not retry blindly after a timeout; the message may already have been sent.

HTTP request

Replace the YOUR_… placeholders. Add channel, channel_source, and profile_id at the top level to identify the customer by channel identity instead of uid.

POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/users/YOUR_UID/messages
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "messages": [
    {
      "type": "message_sent",
      "touchpoint": {
        "channel": "YOUR_CHANNEL",
        "source": "YOUR_SOURCE",
        "id": "YOUR_PROFILE_ID"
      },
      "data": {
        "message": {
          "text": "Hello! How can we help?",
          "format": "plaintext"
        }
      }
    }
  ]
}