SubizDeveloper Docs
Get Started

API 4.0 · 4.1

Subiz API

Connect your systems to Subiz customers, conversations, messages, and webhooks.

Use the Subiz API to sync customer records with your CRM, send messages, coordinate agents, and receive updates on your server.

In Subiz, users are customers and agents are staff. A conversation connects participants with their messages and event history.

Start here

  1. Read the core concepts below to understand the objects and IDs you will use.
  2. Follow Authentication to create an access token for your account.
  3. Test the token with /4.1/me, then choose a task below.

Keep the token on your server. Requests use the issuing agent’s permissions. Replace example IDs and values with those from the account you are integrating.

Choose a task

I want to… Start with
Sync customer records Create a customer or update customer details.
Reply in an existing conversation Send to a conversation, using its conversation ID.
Send through a customer’s channel Send to a customer, using the customer ID and channel destination.
Coordinate staff Invite an agent to participate, or assign an agent responsibility for the conversation.
React to customer or message changes Set up a webhook receiver and read the event payload examples.

For rich content, see Message formats for text, blocks, and links, and Attachments for images, video, audio, and files.

How the entities fit together

When Alex contacts your business, Alex is a user. Sam, the staff member replying, is an agent. Their exchange takes place in a conversation. Each message is carried by an event.

Object Represents
Account The business account your integration connects to.
User A customer record, including attributes and a channel identity.
Agent A staff member serving customers.
Conversation An interaction with participants, an assignee, and event history.
Event Something that happened, such as a message or an assignment.
Message Text, rich blocks, or attachments inside an event.

The examples show selected fields from Subiz’s shared object schemas. They use synthetic values and consistent IDs; they are not complete API responses or create-request bodies. Each endpoint defines which fields it accepts or returns. Empty or optional fields may be omitted.

Keep IDs separate. A customer ID, conversation ID, and external profile ID identify different things. Store the account ID with resource IDs when integrating multiple businesses.

Account

An Account represents a business in Subiz. Its own identifier is id; other objects refer to it as account_id. owner_id identifies the owning agent.

{
  "id": "account_example",
  "name": "Example Store",
  "owner_id": "agent_example",
  "state": "activated"
}

Use an access token for the intended account. See Authentication.

Agent

An Agent is a staff member in an account. Use its id when inviting an agent or setting a conversation’s assignee.

{
  "id": "agent_example",
  "account_id": "account_example",
  "fullname": "Sam Example",
  "email": "sam@example.com",
  "state": "active"
}

fullname is a direct field on an agent. Customer names use an attribute instead.

Users and channel identities

A User is a customer. This customer has a Facebook identity: channel_source identifies the page, while profile_id identifies the profile on that page.

{
  "id": "user_example",
  "account_id": "account_example",
  "channel": "facebook",
  "channel_source": "page_example",
  "profile_id": "profile_example",
  "attributes": [
    {
      "key": "fullname",
      "text": "Alex Example"
    }
  ]
}

Keep the Subiz id separate from profile_id. Use Find or create by channel identity to resolve the channel, source, and profile to a Subiz user.

Attribute

Each item in user.attributes is an Attribute. Locate it by key, not array position. This attribute stores the customer’s name:

{
  "key": "fullname",
  "text": "Alex Example"
}

Read the value field appropriate to the attribute: text, number, boolean, or datetime. A datetime value is a date-time string. Do not assume every attribute uses text.

Touchpoint

A Touchpoint describes a conversation’s channel context or a message destination. For this Facebook example, source is the page and id is the customer’s profile on that page:

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

These correspond to the user’s channel, channel_source, and profile_id above. The meaning of a touchpoint’s id depends on the channel; it can also identify a comment or another destination. Use the connected integration’s values, not a Subiz user ID in place of the destination.

Conversations, members, and ownership

A Conversation has its own ID, members, channel context, and event history. A customer can participate in more than one conversation. Here, Sam is both a member and the responsible agent:

{
  "id": "conversation_example",
  "account_id": "account_example",
  "state": "active",
  "assignee": "agent_example",
  "members": [
    {
      "id": "user_example",
      "type": "user",
      "membership": "active"
    },
    {
      "id": "agent_example",
      "type": "agent",
      "conversation_id": "conversation_example",
      "membership": "active"
    }
  ],
  "touchpoint": {
    "channel": "facebook",
    "source": "page_example",
    "id": "profile_example"
  }
}

assignee identifies the responsible agent. It can be empty or omitted when the conversation is unassigned. members describes participation; it is not the same as ownership.

Conversation member

A ConversationMember identifies a participant by type and id. membership records their participation state.

{
  "id": "agent_example",
  "type": "agent",
  "conversation_id": "conversation_example",
  "membership": "active"
}

Invite an agent adds an existing agent as a participant. Assign an agent changes responsibility. Explicit assignment does not add the agent to members.

Messages and events

Message

A Message holds content. This plain-text message belongs to the conversation above:

{
  "conversation_id": "conversation_example",
  "format": "plaintext",
  "text": "Hello Alex"
}

This is the message object, not the full send-request body. Send to a conversation wraps it in data.message and takes the conversation ID from the URL. Send to a customer uses a different request shape and requires channel destination context.

Event data

Data holds the object relevant to an event. For message_sent, it contains message:

{
  "message": {
    "conversation_id": "conversation_example",
    "format": "plaintext",
    "text": "Hello Alex"
  }
}

Other event types can carry user or conversation instead. Check the event’s type before accessing nested fields.

Actor

The optional By object identifies who caused an event. It appears as event.by:

{
  "id": "agent_example",
  "type": "agent"
}

type can identify a user, agent, or bot. The actor is not necessarily the conversation’s assignee. Some events omit by or provide device context without an actor ID.

Event

An Event combines its identity, type, time, actor, and data. Here is the complete example envelope around the message above:

{
  "id": "event_example_1",
  "account_id": "account_example",
  "created": 1794614400000,
  "type": "message_sent",
  "by": {
    "id": "agent_example",
    "type": "agent"
  },
  "data": {
    "message": {
      "conversation_id": "conversation_example",
      "format": "plaintext",
      "text": "Hello Alex"
    }
  }
}

created is the time recorded in Subiz, in Unix milliseconds. event_time, when provided, records the original occurrence time. Event id identifies the event; do not substitute a nested message or conversation ID.

Conversation history contains events, not only messages. A message_sent event or a successful send response does not by itself confirm delivery to an external channel.

Rich messages with blocks

For the full guide to plaintext, links, and text styling, see Message formats.

Block

A Block is a node in a rich-content tree. type selects the node, content holds children, and a text node uses text. Text nodes can include bold, italic, or underline.

{
  "type": "paragraph",
  "content": [
    {
      "type": "text",
      "text": "Hello "
    },
    {
      "type": "text",
      "text": "Alex",
      "bold": true
    }
  ]
}

This content reads “Hello Alex”. A block is a JSON object, not an HTML string.

Rich message

Place the block in message.block and set format to block:

{
  "conversation_id": "conversation_example",
  "format": "block",
  "block": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Hello "
      },
      {
        "type": "text",
        "text": "Alex",
        "bold": true
      }
    ]
  }
}

Subiz can derive plain text while retaining the block tree. Store the tree if you need formatting. The model also supports images, links, lists, and tables; rendering depends on the destination channel.

Attachment

See Attachments for image, video, audio, file, and interactive examples.

Each item in message.attachments is an Attachment. This file example uses a placeholder URL; size is measured in bytes:

{
  "type": "file",
  "mimetype": "application/pdf",
  "url": "https://example.com/guide.pdf",
  "name": "guide.pdf",
  "size": 2048
}

Put attachment objects in the attachments array, not in block.content. A message can contain attachments even when its text is empty.

Webhooks connect your system

API calls request actions; webhooks notify your integration of events. A webhook delivery wraps events in an events array. The same event example would appear as:

{
  "events": [
    {
      "id": "event_example_1",
      "account_id": "account_example",
      "created": 1794614400000,
      "type": "message_sent",
      "by": {
        "id": "agent_example",
        "type": "agent"
      },
      "data": {
        "message": {
          "conversation_id": "conversation_example",
          "format": "plaintext",
          "text": "Hello Alex"
        }
      }
    }
  ]
}

A delivery can contain several events. Verify its signature, then process every event by type and deduplicate by (account_id, id).

See Receive webhook events for setup and Event payload examples for other event types. The delivery envelope is not the Webhook configuration object.

API requests and versions

Send requests to https://api.subiz.com.vn. Each endpoint page shows the full URL, HTTP method, headers, and JSON body when required.

These docs cover API 4.0 and 4.1. Use the version in each endpoint’s URL exactly as shown; different operations can use different versions. See the Changelog for documentation updates and API change announcements.

Before going live

Use with your tools

Read this page as Markdown. For AI tools, use the documentation index or full documentation.