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 alhambra apidaze aspsms athena bandwidth flowroute ixica netplanet siptrunk skyetel telnyx twilio vetta voicemeup voipms voxtelesys
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.
enb_duplicate_active_session	No	Integer	Whether to allow creating a new session when an active session with the same sender and receiver already exists. Valid value: 0: Disallow (default). 1: Allow. A new session can be created even if an active session with the same sender and receiver already exists. After creation, the original session will be removed from the previous handler's session list and taken over by the new creator with the complete chat history.
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 / Alhambra IT / Athenna / IXICA / NETPLANET / Vetta / VoIP.ms / Voxtelesys 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 Aspsms user_key password 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.

Parameter

Required

Type

Description

Yes

String

The name of the key field required by the service provider.Valid value:

For General / Alhambra IT / Athenna / IXICA / NETPLANET / Vetta / VoIP.ms / Voxtelesys
- 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 Aspsms
- user_key
- password
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

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).

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.
enb_duplicate_active_session	No	Integer	Whether to allow creating a new session when an active session with the same sender and receiver already exists. Valid value: 0: Disallow (default). 1: Allow. A new session can be created even if an active session with the same sender and receiver already exists. After creation, the original session will be removed from the previous handler's session list and taken over by the new creator with the complete chat history.

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).

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.

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

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

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: 192.168.5.150:8088
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"
                }
            ]
        }
    ],
   "enb_duplicate_active_session":1
}

Add a WhatsApp channel

POST /openapi/v1.0/message_channel/create?access_token=EX8zZM5hdq3krlPcNmBbDSqfKF1ovibL HTTP/1.1
Host: 192.168.5.150:8088
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,
   "enb_duplicate_active_session":1
}

Add a Facebook channel

POST /openapi/v1.0/message_channel/create?access_token=EX8zZM5hdq3krlPcNmBbDSqfKF1ovibL HTTP/1.1
Host: 192.168.5.150:8088
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
}

Follow us

Follow us

Add a Message Channel

Request URL

Request parameters

Response parameters

Examples

Follow us

Business Needs

Ecosystem

Business Communication Suite

Ticketing System

Training

Frequently Asked Questions

Contact Us

Visit our Office

Add a Message Channel

Request URL

Request parameters

Response parameters

Examples