添加消息渠道

添加并配置消息渠道。

注： 此 API 接口用于创建 SMS 带薪渠道、WhatsApp 消息渠道或 Facebook 消息渠道。如需创建在线咨询渠道，请参见 添加在线咨询渠道。

请求 URL

POST {base_url}/{api_path}/message_channel/create?access_token={access_token}

请求参数

根据不同类型的消息渠道发送请求参数。
添加 SMS 短信渠道
参数 是否必填 类型 说明
name 是 String 消息渠道名称。
注： 长度不可超过 127 个字符。
webhook_url_type 是 String Webhook URL 所使用的域名类型。
取值范围：
  • fqdn：Yeastar FQDN。
  • nat：通过 NAT 映射公网 IP 后的域名。
channel 是 String 消息渠道的运营商。
取值范围：
  • general：通用。
  • apidaze
  • athena
  • bandwidth
  • flowroute
  • ixica
  • siptrunk
  • skyetel
  • telnyx
  • twilio
  • vetta
  • voicemeup
account_data 是 Array<Auth_Info> 运营商要求的消息渠道连接所需信息。
send_rate 否 Integer 指定 PBX 通过消息渠道每秒可发送的消息数量。
auto_close_session 否 Integer 是否自动关闭在指定时间内无任何互动的消息会话。
session_expired_time 否 Integer 会话超时时间 (天)。消息会话在超过此指定时间未有任何互动后将自动关闭。
accompanying_msg 否 String 发送聊天文件时附带的默认文本内容。
注： 此参数在创建 Apidaze SMS 短信渠道时必填。
dids 否 Array<Msg_Routing> 定义消息路由规则，包括添加 DID 号码、设置消息接收目的地和指定允许通过指定 DID 号码创建会话的成员。
Auth_Info
注： 根据不同运营商的要求提供所需的参数值。
参数 是否必填 类型 说明
k 是 String 运营商要求的信息字段的名称。
取值范围：
  • General / Athenna / IXICA / Vetta
    • api_key
    • api_secret (选填)
    • api_verify_url (选填)：用于验证鉴权信息的 API 接口地址。
    • api_send_url：用于发送消息的 API 接口地址。
  • Apidaze
    • api_key
    • api_secret
  • Bandwidth
    • application_id
    • account_id
    • username
    • password
  • Flowroute / SIPTRUNK
    • access_key
    • secret_key
  • Skyetel
    • sid_key
    • secret_key
  • Telnyx
    • api_key
    • public_key
  • Twilio
    • account_sid
    • auth_token
  • VoiceMeUp
    • username
    • auth_token
v 是 String 信息字段 (k) 的对应值。

取值范围：

  • 若 k 为 api_verify_url 或 api_send_url，输入 API 接口地址，如 https://{{your-endpoint}}。
  • 对于其他信息字段，请以 Base64 编码 格式输入对应的值。
Msg_Routing
参数 是否必填 类型 说明
did_number 是 String 消息渠道绑定的 DID 号码。
destination_type 是 String 消息接收目的地类型。

取值范围：

  • extension：分机用户。
  • queue：消息队列。
  • api：第三方分析平台 (消息通过二次开发接口传递)。
destination_id 否 String 消息接收目的地的 ID。
注：
members 否 Array<Members> 允许使用此 DID 号码创建会话以发送消息的成员。
Members
参数 是否必填 类型 说明
type 是 String 成员类型。

取值范围：

  • extension：分机用户。
  • ext_group：分机组。
  • organization：部门。
value 是 String 成员的唯一 ID。
注： 可使用 获取菜单选项 接口查询成员 ID (menu=extension/ext_group/org_list)。
添加 WhatsApp 消息渠道
参数 是否必填 类型 说明
name 是 String 消息渠道名称。
注： 长度不可超过 127 个字符。
webhook_url_type 是 String Webhook URL 所使用的域名类型。
取值范围：
  • fqdn：Yeastar FQDN。
  • nat：通过 NAT 映射公网 IP 后的域名。
channel 是 String 消息渠道的运营商。

取值范围： whatsapp
account_data 是 Array<Auth_Info> 运营商要求的消息渠道连接所需信息。
phone_number_id 是 String WhatsApp 号码 ID。
注： 长度不可超过 31 个字符。
business_account_id 是 String WhatsApp 账户 ID。
注：
  • 请以 Base64 编码 格式输入对应的值。
  • 长度不可超过 500 个字符。
dids 否 Array<Msg_Routing> 定义消息路由规则，包括添加 WhatsApp 号码、设置消息接收目的地和指定允许通过此号码创建会话的成员。
auto_close_session 否 Integer 是否自动关闭在指定时间内无任何互动的消息会话。
session_expired_time 否 Integer 会话超时时间 (天)。消息会话在超过此指定时间未有任何互动后将自动关闭。
Auth_Info
参数 是否必填 类型 说明
k 是 String 运营商要求的信息字段的名称。
取值范围：
  • access_token
  • app_secret
v 是 String 信息字段 (k) 的对应值。
注： 请以 Base64 编码 格式输入对应的值。
Msg_Routing
参数 是否必填 类型 说明
did_number 是 String WhatsApp 号码 (E.164 格式)。
destination_type 是 String 消息接收目的地类型。

取值范围：

  • extension：分机用户。
  • queue：消息队列。
  • api：第三方分析平台 (消息通过二次开发接口传递)。
destination_id 否 String 消息接收目的地的 ID。
注：
members 否 Array<Members> 允许使用此 WhatsApp 号码创建会话以发送消息的成员。
Members
参数 是否必填 类型 说明
type 是 String 成员类型。

取值范围：

  • extension：分机用户。
  • ext_group：分机组。
  • organization：部门。
value 是 String 成员的唯一 ID。
注： 可使用 获取菜单选项 接口查询成员 ID (menu=extension/ext_group/org_list)。
添加 Facebook 消息渠道
参数 是否必填 类型 说明
name 是 String 消息渠道名称。
注： 长度不可超过 127 个字符。
webhook_url_type 是 String Webhook URL 所使用的域名类型。
取值范围：
  • fqdn：Yeastar FQDN。
  • nat：通过 NAT 映射公网 IP 后的域名。
channel 是 String 消息渠道的运营商。

取值范围：facebook
account_data 是 Array<Auth_Info> 运营商要求的消息渠道连接所需信息。
dids 否 Array<Msg_Routing> 定义消息路由规则，包括添加 Facebook 公共主页编号和设置消息接收目的地。
auto_close_session 否 Integer 是否自动关闭在指定时间内无任何互动的消息会话。
session_expired_time 否 Integer 会话超时时间 (天)。消息会话在超过此指定时间未有任何互动后将自动关闭。
Auth_Info
参数 是否必填 类型 说明
k 是 String 运营商要求的信息字段的名称。
取值范围：
  • access_token
  • app_secret
  • page_name：Facebook 公共主页名称。
v 是 String 信息字段 (k) 的对应值。
注： 对于 access_token 和 app_secret 信息字段，请以 Base64 编码 格式输入对应的值。
Msg_Routing
参数 是否必填 类型 说明
did_number 是 String Facebook 公共主页编号。
destination_type 是 String 消息接收目的地类型。

取值范围：

  • extension：分机用户。
  • queue：消息队列。
  • api：第三方分析平台 (消息通过二次开发接口传递)。
destination_id 否 String 消息接收目的地的 ID。
注：

响应参数

表 1.
参数 类型 说明
errcode Integer 返回错误码。
  • 0：请求成功。
  • 非零值：请求失败。
注： 更多错误码和错误信息说明，请参见 错误码 & 错误信息。
errmsg String 返回信息。
  • SUCCESS：请求成功。
  • FAILURE：请求失败。
id Integer 消息渠道的唯一 ID。

示例

请求示例

  • 添加一条通用 SMS 短信渠道
    POST /openapi/v1.0/message_channel/create?access_token=JZvX9J8RddTcKb58WNQF2tXnLwPhrbUY HTTP/1.1

Host: yeastardocs.example.yeastarcloud.com
Content-Type: application/json

{
    "name":"Docs-General SMS Channel",
    "webhook_url_type":"nat",
    "channel":"general",
    "account_data": [
        {
            "k": "api_secret",
            "v": "bXlTdXBlclNlY3JldDEyMw=="
        },
        {
            "k": "api_key",
            "v": "bXlBUElLZXk0NTY="
        },
        {
            "k": "api_verify_url",
            "v": "https://api.example.com/auth/verify"   
        },{
            "k": "api_send_url",
            "v": "https://api.example.com/message/send"
        }
    ],
    "send_rate":2,  
    "auto_close_session":1,
    "session_expired_time": 5,  
      "dids": [
        {
            "did_number": "+1234567890",
            "destination_type": "extension",
            "destination_id": "137",
            "members": [
                {
                    "type": "extension",
                    "value": "137"
                }
            ]
        }
    ]
}
  • 添加一条 WhatsApp 消息渠道
    POST /openapi/v1.0/message_channel/create?access_token=EX8zZM5hdq3krlPcNmBbDSqfKF1ovibL HTTP/1.1

Host: yeastardocs.example.yeastarcloud.com
Content-Type: application/json

{
    "name":"Docs-WhatsApp Channel",
    "webhook_url_type":"fqdn",
    "channel":"whatsapp",
    "account_data": [
        {
            "k": "access_token",
            "v": "bXlTdXBlclNlY3JldDEyMw=="
        },
        {
            "k": "app_secret",
            "v": "bXlBUElLZXk0NTY="
        }
    ],
   
   "phone_number_id":"3546573434879",
   "business_account_id":"MzQ1Njc4Nzg5MA==",   
   "dids": [
        {
            "did_number": "+15567778888",
            "destination_type": "queue",
            "destination_id": "4"
         
        }
    ],
   "auto_close_session":1,
   "session_expired_time": 5
}
  • 添加一条 Facebook 消息渠道
    POST /openapi/v1.0/message_channel/create?access_token=EX8zZM5hdq3krlPcNmBbDSqfKF1ovibL HTTP/1.1

Host: yeastardocs.example.yeastarcloud.com
Content-Type: application/json

{
    "name":"Docs-Facebook Channel",
    "webhook_url_type":"fqdn",
    "channel":"facebook",
    "account_data": [
        {
            "k": "access_token",
            "v": "bXlTdXBlclNlY3JldDEyMw=="
        },
        {
            "k": "app_secret",
            "v": "bXlBUElLZXk0NTY="
        },
        {
            "k": "page_name",
            "v": "test-facebook-page"
        }
    ],
   "dids": [
        {
            "did_number": "12345678901234", 
            "destination_type": "queue",
            "destination_id": "4" 
         
        }
    ],
   "auto_close_session":1,
   "session_expired_time": 5
}

响应示例

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 19
}