如何向API通道发送消息

由于API Channel不支持隐式创建联系人。Livedesk 使用 API Channel，分为以下三步：

创建联系人
基于联系人信息创建会话
发送消息

创建联系人

调用地址

https://livedesk-api.engagelab.com/api/v2/accounts/contacts

请求示例

curl -X POST https://livedesk-api.engagelab.com/api/v2/accounts/contacts \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)' \ { "inbox_id": 407, "name": "Test", // 选填 "email": "alice@acme.inc", "phone_number": "+123456789", "avatar_url": "https://example.com/avatar.png", "identifier": "1234567890", }

              
              curl -X POST https://livedesk-api.engagelab.com/api/v2/accounts/contacts \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
{
    "inbox_id": 407,
    "name": "Test",                   // 选填
    "email": "alice@acme.inc",
    "phone_number": "+123456789", 
    "avatar_url": "https://example.com/avatar.png",
    "identifier": "1234567890",
}

此代码块在浮窗中显示

请求头

字段	类型	描述
Authorization	string	使用 `Authorization: Basic base64(API Key:API Secret)` 进行身份验证。请前往 API 密钥页面获取 API Key 和 API Secret，并将两者以冒号连接后进行 Base64 编码。
Content-Type	application/json	数据类型，普通文字消息使用 application/json。

请求体参数

字段	类型	必填	描述
inbox_id	String	是	channel ID.对应「项目设置-Channels-具体channel-设置」里面的Channel ID.
name	String	否	联系人名称。
email	String	否	邮件地址。
phone_number	String	否	联系方式。
avatar_url	String	否	附件链接。
identifier	String	否	用户标识。

响应示例

{ "payload": { "contact": { "additional_attributes": {}, "availability_status": "offline", "email": null, "id": 2219259, "name": "Test", "phone_number": null, "blocked": false, "identifier": null, "thumbnail": "", "custom_attributes": {}, "created_at": 1766571703, "contact_inboxes": [] }, "contact_inbox": { "inbox": null, "source_id": null } } }

              
              {
    "payload": {
        "contact": {
            "additional_attributes": {},
            "availability_status": "offline",
            "email": null,
            "id": 2219259,
            "name": "Test",
            "phone_number": null,
            "blocked": false,
            "identifier": null,
            "thumbnail": "",
            "custom_attributes": {},
            "created_at": 1766571703,
            "contact_inboxes": []
        },
        "contact_inbox": {
            "inbox": null,
            "source_id": null
        }
    }
}

此代码块在浮窗中显示

响应参数

字段	类型	必填	描述
additional_attributes	Object	否	附件属性。
availability_status	String	否	在线状态，默认为offline。
email	String	否	邮件地址。
id	String	否	联系人ID。
name	String	否	名称
phone_number	String	否	手机号码。
blocked	String	否	是否锁定，默认falese。
identifier	String	否	用户标识。
thumbnail	String	否	用户标识。
custom_attributes	String	否	客户属性。
created_at	String	否	创建时间戳。
contact_inboxes	Array	否	用户标识。
inbox	String	否	channel通道。
source_id	String	否	来源ID。

创建会话

调用地址

https://livedesk-api.engagelab.com/api/v2/accounts/conversations

请求示例

curl -X POST https://livedesk-api.engagelab.com/api/v2/accounts/conversations \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)' \ { "inbox_id": 407, // 必传 "contact_id": 2219256, // contact_id、source_id 可选其中一个传，但必须保证能正确标识发送者 "source_id": "123456789" }

              
              curl -X POST https://livedesk-api.engagelab.com/api/v2/accounts/conversations \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
{
  "inbox_id": 407,              // 必传
  "contact_id": 2219256,        // contact_id、source_id 可选其中一个传，但必须保证能正确标识发送者
  "source_id": "123456789"
}

此代码块在浮窗中显示

请求头参数

字段	类型	描述
Authorization	string	使用 `Authorization: Basic base64(API Key:API Secret)` 进行身份验证。请前往 API 密钥页面获取 API Key 和 API Secret，并将两者以冒号连接后进行 Base64 编码。
Content-Type	application/json	数据类型，普通文字消息使用 application/json。

请求体参数

字段	类型	必填	描述
inbox_id	String	是	channel ID。与创建联系人接口使用的ID一致。
contact_id	String	否	联系人ID。创建联系人接口响应中的id
source_id	String	否	来源ID。

响应示例

{ "meta": { "sender": { "additional_attributes": {}, "availability_status": "offline", "email": null, "id": 2219256, "name": "wjTest", "phone_number": null, "blocked": false, "identifier": null, "thumbnail": "", "custom_attributes": {}, "created_at": 1766571624 }, "channel": "Channel::Api", "hmac_verified": false }, "id": 40, "messages": [], "account_id": 17623000010928, "uuid": "660ce36f-46bb-4153-948c-8a26e6dab634", "inbox_id": 407, "additional_attributes": {}, "agent_last_seen_at": 0, "assignee_last_seen_at": 0, "can_reply": true, "contact_last_seen_at": 0, "custom_attributes": {}, "labels": [], "muted": false, "snoozed_until": null, "status": "open", "priority": null, "conversation_category": "chat", "chat_mode": "private_chat", "is_forum": false, "created_at": 1766572062, "updated_at": 1766572062.5803902, "timestamp": 1766572062, "first_reply_created_at": 0, "unread_count": 0, "last_non_activity_message": null, "last_activity_at": 1766572062, "waiting_since": 1766572062, "sla_policy_id": null, "ticket_id": null, "over_limit": false, "content_preview": { "content": null, "message_type": null, "created_at": null }, "platform": { "channel_type": "Channel::Api", "inbox_name": "JennyApi", "inbox_id": 407 }, "account_info": { "contact_name": "wjTest", "contact_email": null, "contact_phone": null, "contact_id": 2219256, "contact_avatar": "" }, "assignment": { "assignee_id": null, "assignee_name": null, "assignee_email": null, "team_id": null, "team_name": null } }

              
              {
    "meta": {
        "sender": {
            "additional_attributes": {},
            "availability_status": "offline",
            "email": null,
            "id": 2219256,
            "name": "wjTest",
            "phone_number": null,
            "blocked": false,
            "identifier": null,
            "thumbnail": "",
            "custom_attributes": {},
            "created_at": 1766571624
        },
        "channel": "Channel::Api",
        "hmac_verified": false
    },
    "id": 40,
    "messages": [],
    "account_id": 17623000010928,
    "uuid": "660ce36f-46bb-4153-948c-8a26e6dab634",
    "inbox_id": 407,
    "additional_attributes": {},
    "agent_last_seen_at": 0,
    "assignee_last_seen_at": 0,
    "can_reply": true,
    "contact_last_seen_at": 0,
    "custom_attributes": {},
    "labels": [],
    "muted": false,
    "snoozed_until": null,
    "status": "open",
    "priority": null,
    "conversation_category": "chat",
    "chat_mode": "private_chat",
    "is_forum": false,
    "created_at": 1766572062,
    "updated_at": 1766572062.5803902,
    "timestamp": 1766572062,
    "first_reply_created_at": 0,
    "unread_count": 0,
    "last_non_activity_message": null,
    "last_activity_at": 1766572062,
    "waiting_since": 1766572062,
    "sla_policy_id": null,
    "ticket_id": null,
    "over_limit": false,
    "content_preview": {
        "content": null,
        "message_type": null,
        "created_at": null
    },
    "platform": {
        "channel_type": "Channel::Api",
        "inbox_name": "JennyApi",
        "inbox_id": 407
    },
    "account_info": {
        "contact_name": "wjTest",
        "contact_email": null,
        "contact_phone": null,
        "contact_id": 2219256,
        "contact_avatar": ""
    },
    "assignment": {
        "assignee_id": null,
        "assignee_name": null,
        "assignee_email": null,
        "team_id": null,
        "team_name": null
    }
}

此代码块在浮窗中显示

响应参数

字段	类型	必填	描述
meta	Object	否	元数据对象。
sender	Object	否	发送者信息。
additional_attributes	Object	否	额外属性。
availability_status	String	否	可用性状态。
email	Null	否	邮箱。
id	Number	否	联系人ID。
name	String	否	发送者名称。
phone_number	Null	否	电话号码。
blocked	Boolean	否	是否被阻止。
identifier	Null	否	用户属性标识。
thumbnail	String	否	缩略图。
custom_attributes	Object	否	自定义属性。
created_at	Number	否	会话创建时间戳。
channel	String	否	渠道类型。
hmac_verified	Boolean	否	HMAC验证状态。
id	Number	否	会话ID。
messages	Array	否	消息数组。
account_id	Number	否	项目ID
uuid	String	否	唯一标识符。
inbox_id	Number	否	通道ID。
additional_attributes	Object	否	额外属性。
agent_last_seen_at	Number	否	代理最后处理时间。
assignee_last_seen_at	Number	否	被分配最后处理时间。
can_reply	Boolean	否	是否可以回复。
contact_last_seen_at	Number	否	联系人最后seen时间。
custom_attributes	Object	否	自定义属性。
labels	Array	否	标签数组。
muted	Boolean	否	是否静音。
snoozed_until	Null	否	暂停到何时。
status	String	否	状态。
priority	Null	否	优先级。
conversation_category	String	否	对话类别。
chat_mode	String	否	聊天模式。
is_forum	Boolean	否	是否为论坛。
created_at	Number	否	创建时间戳。
updated_at	Number	否	更新时间戳。
timestamp	Number	否	时间戳。
first_reply_created_at	Number	否	首次回复创建时间。
unread_count	Number	否	未读计数。
last_non_activity_message	Null	否	最后非活动消息。
last_activity_at	Number	否	最后活动时间。
waiting_since	Number	否	等待开始时间。
sla_policy_id	Null	否	SLA策略ID。
ticket_id	Null	否	工单ID。
over_limit	Boolean	否	是否超限。
content_preview	Object	否	内容预览。
content_preview.content	Null	否	预览内容。
content_preview.message_type	Null	否	消息类型。
content_preview.created_at	Null	否	创建时间。
platform	Object	否	平台信息。
channel_type	String	否	渠道类型。
inbox_name	String	否	收件箱名称。
inbox_id	Number	否	收件箱ID。
account_info	Object	否	账户信息。
contact_name	String	否	联系人名称。
contact_email	Null	否	联系人邮箱。
contact_phone	Null	否	联系人电话。
contact_id	Number	否	联系人ID。
contact_avatar	String	否	联系人头像。
assignment	Object	否	分配信息。
assignee_id	Null	否	受理人ID。
assignee_name	Null	否	受理人名称。
assignee_email	Null	否	受理人邮箱。
team_id	Null	否	团队ID。
team_name	Null	否	团队名称。

发送消息

调用地址

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages

请求示例

curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)' \ -d '{ "content": "客服发送消息，正常吗", "private": false, "message_type": "incoming"， "content_attributes": { "in_reply_to": 29 } }'

              
              curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
-d '{
    "content": "客服发送消息，正常吗",  
    "private": false,
    "message_type": "incoming"，
    "content_attributes": {
        "in_reply_to": 29   
    }
}'

此代码块在浮窗中显示

请求头

字段	类型	描述
Authorization	string	使用 `Authorization: Basic base64(API Key:API Secret)` 进行身份验证。请前往 API 密钥页面获取 API Key 和 API Secret，并将两者以冒号连接后进行 Base64 编码。
Content-Type	application/json	数据类型，普通文字消息使用 application/json。

请求体参数

字段	类型	必填	描述
content	String	否	channel ID.对应「项目设置-Channels-具体channel-设置」里面的Channel ID.
private	String	否	联系人名称。
message_type	String	否	消息类型，outgoing、incoming。分别表示客服发送、用户发送。不传默认为outgoing。
content_attributes	String	否	内容属性。
in_reply_to	String	否	回复内容。