Add a Message Channel

Add and configure a message channel.

Note: This API endpoint can be used to create an SMS channel, WhatsApp channel, or Facebook channel. To create a Live Chat channel, see Add a Live Chat Channel.

Request URL

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

Request parameters

Send different request parameters according to different types of message channel.

Add an SMS channel
Add a WhatsApp channel
Add a Facebook channel

Add an SMS channel


Parameter	Required	Type	Description
name	Yes	String	Message channel name. Note: The length must not exceed 127 characters.
webhook_url_type	Yes	String	The type of domain used in the Webhook URL. Valid value: `fqdn` `nat`
channel	Yes	String	The service provider of the message channel. Valid value: `general` `apidaze` `athena` `bandwidth` `flowroute` `ixica` `siptrunk` `skyetel` `telnyx` `twilio` `vetta` `voicemeup`
account_data	Yes	Array<Auth_Info>	The data required by the service provider for message channel connection.
send_rate	No	Integer	Specify the number of messages that PBX can send per second via the message channel.
auto_close_session	No	Integer	Whether to automatically close a message session after it has been inactive for a specified period of time.
session_expired_time	No	Integer	The duration of inactivity (in days) after which a session is automatically closed.
accompanying_msg	No	String	The accompanying text content for chat file. Note: This parameter is REQUIRED when creating an Apidaze SMS channel.
dids	No	Array<Msg_Routing>	Define the message routing rule by adding the DID number(s), setting message destination, and specifying members that are allowed to initiate message sessions via specified DID number.

Auth_Info

Note: Provide the required parameter values according to the requirements of different SMS service providers.


Parameter	Required	Type	Description
k	Yes	String	The name of the key field required by the service provider. Valid value: For General / Athenna / IXICA / Vetta `api_key` `api_secret` (Optional) `api_verify_url` (Optional): API endpoint for authentication verification. `api_send_url`: API endpoint for sending messages. For Apidaze `api_key` `api_secret` For Bandwidth `application_id` `account_id` `username` `password` For Flowroute / SIPTRUNK `access_key` `secret_key` For Skyetel `sid_key` `secret_key` For Telnyx `api_key` `public_key` For Twilio `account_sid` `auth_token` For VoiceMeUp `username` `auth_token`
v	Yes	String	The value associated with the key field `k`. Valid value: If `k` is `api_verify_url` or `api_send_url`, enter the API endpoint as `https://{{your-endpoint}}`. For all other key fields, enter the key value in Base64-encoded format.

Msg_Routing


Parameter	Required	Type	Description
did_number	Yes	String	The DID number associated with the message channel.
destination_type	Yes	String	The type of the destination. Valid value: `extension`: Extension user. `queue`: Message queue. `api`: Third-party message analytics platform (via API).
destination_id	No	String	The unique ID of destination to which inbound messages are sent. Note: This parameter is REQUIRED when the `destination_type` is set to `extension` or `queue`. You can query the extension ID using Search Specific Extensions, and query the message queue ID using Search Specific Message Queues.
members	No	Array<Members>	The members that are allowed to initiate message sessions using the DID number.

Members


Parameter	Required	Type	Description
type	Yes	String	Member type. Valid value: `extension` `ext_group` `organization`
value	Yes	String	The unique ID of the member. Note: You can query the member ID using Get Menu Options (`menu`=`extension`/`ext_group`/`org_list`).

Add a WhatsApp Channel


Parameter	Required	Type	Description
name	Yes	String	Message channel name. Note: The length must not exceed 127 characters.
webhook_url_type	Yes	String	The type of domain used in the Webhook URL. Valid value: `fqdn` `nat`
channel	Yes	String	The service provider of the message channel. Valid value: `whatsapp`
account_data	Yes	Array<Auth_Info>	The data required by the service provider for message channel connection.
phone_number_id	Yes	String	The ID of the WhatsApp phone number. Note: The length must not exceed 31 characters.
business_account_id	Yes	String	The ID of the WhatsApp business account. Note: The value should be passed in Base64-encoded format. The length must not exceed 500 characters.
dids	No	Array<Msg_Routing>	Define the message routing rule by adding the WhatsApp phone number, setting message destination, and specifying members that are allowed to initiate message sessions via the phone number.
auto_close_session	No	Integer	Whether to automatically close a message session after it has been inactive for a specified period of time.
session_expired_time	No	Integer	The duration of inactivity (in days) after which a session is automatically closed.

Auth_Info


Parameter	Required	Type	Description
k	Yes	String	The name of the key field required by the service provider. Valid value: `access_token` `app_secret`
v	Yes	String	The value associated with the key field `k`. Note: The value should be passed in Base64-encoded format.

Msg_Routing


Parameter	Required	Type	Description
did_number	Yes	String	The WhatsApp phone number in E.164 format.
destination_type	Yes	String	The type of the destination. Valid value: `extension`: Extension user. `queue`: Message queue. `api`: Third-party message analytics platform (via API).
destination_id	No	String	The unique ID of destination to which inbound messages are sent. Note: This parameter is REQUIRED when the `destination_type` is set to `extension` or `queue`. You can query the extension ID using Search Specific Extensions, and query the message queue ID using Search Specific Message Queues.
members	No	Array<Members>	The members that are allowed to initiate message sessions via the WhatsApp phone number.

Members


Parameter	Required	Type	Description
type	Yes	String	Member type. Valid value: `extension` `ext_group` `organization`
value	Yes	String	The unique ID of the member. Note: You can query the member ID using Get Menu Options (`menu`=`extension`/`ext_group`/`org_list`).

Add a Facebook Channel


Parameter	Required	Type	Description
name	Yes	String	Message channel name. Note: The length must not exceed 127 characters.
webhook_url_type	Yes	String	The type of domain used in the Webhook URL. Valid value: `fqdn` `nat`
channel	Yes	String	The service provider of the message channel. Valid value: `facebook`
account_data	Yes	Array<Auth_Info>	The data required by the service provider for message channel connection.
dids	No	Array<Msg_Routing>	Define the message routing rule by adding the Facebook page ID and setting message destination.
auto_close_session	No	Integer	Whether to automatically close a message session after it has been inactive for a specified period of time.
session_expired_time	No	Integer	The duration of inactivity (in days) after which a session is automatically closed.

Auth_Info


Parameter	Required	Type	Description
k	Yes	String	The name of the key field required by the service provider. Valid value: `access_token` `app_secret` `page_name`
v	Yes	String	The value associated with the key field `k`. Note: For `access_token` and `app_secret` fields, enter the value in Base64-encoded format.

Msg_Routing


Parameter	Required	Type	Description
did_number	Yes	String	Facebook page ID.
destination_type	Yes	String	The type of the destination. Valid value: `extension`: Extension user. `queue`: Message queue. `api`: Third-party message analytics platform (via API).
destination_id	No	String	The unique ID of destination to which inbound messages are sent. Note: This parameter is REQUIRED when the `destination_type` is set to `extension` or `queue`. You can query the extension ID using Search Specific Extensions, and query the message queue ID using Search Specific Message Queues.

Response parameters

Table 1.
Parameter	Type	Description
errcode	Integer	Returned error code. `0`: Succeed. Non-zero value: Failed. Note: You can check the error code and error message in Error Code and Error Message.
errmsg	String	Returned message. `SUCCESS`: Succeed. `FAILURE`: Failed.
id	Integer	The unique ID of the message channel.

Examples

Request example

Add an general SMS channel

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"
                }
            ]
        }
    ]
}

Add a WhatsApp channel

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
}

Add a Facebook channel

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
}

Response example

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