🏪Create conversations for online and offline channels

This API is used to create a new "text call" conversation record in the system, typically triggered by external entry points (such as a website Web Form, online interactive form, or third-party service). Developers can use this endpoint to write the user's input text message into the system and, as needed, specify or associate it with an existing contact／onsite_contact. If not specified or if the specified target does not exist, the system will automatically create and attach it according to the rules.

Related Terms

Name	Description	System field / example	Usage scenario
contact_id	The system identifier number for the "customer" in the system.	contact_id = 1001	When you already know the customer ID and want to attach the message directly under that customer.
onsite_contact	Online/offline channel contact. It is an intermediary layer representing the customer's identity under a specific Onsite account.	—	Used to distinguish conversations from different channels, for example the same customer interacting via website form, in-store, or app.
onsite_contact_id	onsite_contact The system identification number. The system will automatically generate a unique ID.	onsite_contact_id = 501	When you already know the target onsite_contact, you can pass this ID directly to attach the message.
onsite_contact_sn	onsite_contact An independent identification field (serial number). It usually stores a "member number" or other unique string, chosen and maintained by the caller.	onsite_contact_sn = "VIP-A0001"	If you want to use an external system's member number or identifier as the lookup key, store it in sn, then pass this value later so the system can match it.
message	The message content to be written this time.	"Wants to inquire about product stock"	The actual conversation text, which may originate from a Web Form, online form, or other input.
onsite_account	Online channel account; one account represents one "channel source." You can create different accounts by region or website version, for example "Taiwan website" or "Japan website."	onsite_account_id=1	When the same brand has multiple official websites or channels and needs to track message sources separately.

---

API

curl -X POST "api/onsite-account/{onsite_account}/text-call" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>"

Response

Returned in JSON format,

• HTTP status = 200 → indicates creation success

• HTTP status = 422 → validation error

• Others → handle according to the error code

URL Parameters

Parameter	Description
onsite_account	Required, targetonline/offline channel account unique identifier (string | int)

Request Body

Content-Type: application/json

Field name	Type	Rules / conditions	Description
identifier_type	string	contact_id / onsite_contact_id / onsite_contact_sn / null	Specify the identification method; if null, the system will handle it automatically.
identifier	int/string/null	Depends on identifier_type	The corresponding actual value, e.g. contact_id=1001; if null, the system will create it automatically.
message	string	Required, length 1–5000	Message content.
should_enter_queue	boolean	nullable; true/false	If true → the conversation status will be immediately moved to the transfer queue to wait.
assignee_id	integer	nullable; must exist in employees.id	Specify the customer service/employee ID to handle it. If not filled → the system will handle it according to queue or routing rules.
interact_collection_data	object	nullable	Service record data that can be pre-written at the time the conversation is created. Used to automatically populate service record fields (such as notes, custom fields, etc.) after pickup, reducing manual completion by agents, lowering error rates and improving processing efficiency. Its content format is: { "memo": "Default filled note", "cz_cols": [ { "id": 230, "value": "Default filled #001" }, { "id": 226, "value": "Default filled #002" } ] }

---

Business Rules

1. How the target object is determined

   • If you include identifier_type + identifier → it will look for the target according to the method you provided.

   • If you do not include it → the system will automatically create a onsite_contact, and then attach this message under that object.

2. What happens when the target cannot be found

   • onsite_contact_sn: Suppose the SN (serial number) you passed does not exist in the system → the system will create a new onsite_contact, and record this SN.

   • contact_id: If the member (contact) exists but the customer does not yet have a onsite_contact → the system will automatically create one for them and attach the message. If this contact_id does not exist at all it will be rejected.

   • onsite_contact_id: If the ID you specified cannot be found in the system it will be rejected.

3. Message handling

   • In any case, each API call will definitely add a message, and it will always be associated with some onsite_contact relation.

4. should_enter_queue = false or null

   • Only create a conversation record without triggering immediate customer service assignment; it requires manual pickup.

Simulation scenario

Assume there is a customer who left a message on your website Web Form, and you know their member number, and through the contact customer API obtained their system ID as 1001, so (contact_id = 1001) :

• Call the API

  {
    "identifier_type": "contact_id",
    "identifier": 1001,
    "message": "Customer wants to inquire about product stock, contact method is [email protected]"
  }

• System processing logic

  1. First check whether contact_id = 1001 exists.

  2. If the member does not yet have a corresponding onsite_contact, the system will automatically create one and attach this message.

  3. Finally get a "message record" and bind it to this member's onsite_contact .

---

Example

1) No specified target

{
  "message": "Hello"
}

2) Specify onsite_contact_sn

{
  "identifier_type": "onsite_contact_sn",
  "identifier": "A0001",
  "message": "Hello"
}

3) Specify contact_id

{
  "identifier_type": "contact_id",
  "identifier": 1,
  "message": "Hello"
}

4) Specify onsite_contact_id

{
  "identifier_type": "onsite_contact_id",
  "identifier": 1,
  "message": "Hello"
}

Development Best Practices

In practical API development, priority should be given to how to avoid duplicate data and extra manual work, ensuring agents can reply to customers with the shortest possible workflow.

First scenarioIf the customer record does not yet exist in the system, it is recommended to first create the customer via the Contact API, then immediately add their email or phone contact information, so that agents can reply directly to the customer after picking up the conversation without having to go back to supplement or correct data.

Second scenarioIf the customer data already exists in the system, you should query via the API and associate with the existing customer, then create the new conversation record instead of creating a duplicate customer. This design not only maintains data integrity and reduces the information burden caused by duplicate records, but also improves agents' operational efficiency and user experience.

First call the Contact API to find possible customers
    ├── Exists
    │       └── Directly pass into the api/onsite-account API to create the conversation
    │
    └── Does not exist
            └── Call the Contact API to create a new customer
                    └── Add contact methods (Email / Phone)
                            └── Then pass into the api/onsite-account API to create the conversation