Description Of The Request Parameters

Description of the request parameters

Name Mandatory Description
Main      
1 phone_number Yes Phone number of User.
▪It is given in the international format without the«+»sign.
2 channels Yes List of Message delivery channels.
▪Any combination without duplicates, e.g.Viber + SMSorPush+ Viber+ SMS.
3 channel_options Yes Have to be specified for each communication channel.
4 messages Yes The list of phonenumbers of Users and texts will be transmitted to all communication channels.
▪For batch request.
5 recipients Yes List of parameters for personalized campaign.
▪For broadcast request.
6 extra_id No External identifier of the Message(specified by you).
▪Maximum length: 64 characters.
7 callback_url No Message reports will be sent to this URL.
▪Maximum length: 256 characters.
8 start_time No Scheduled date of campaign start.
▪Shall be specified in the following format: “YYYY-MM-DD hh:mm:ss±hh:mm
▪If the difference with time according to Greenwich Mean Time (in the format +03:00) is not specified, then the difference according to Kyiv time is calculated.
9 tag No Campaign name.
▪Maximum length: 64 characters.
Viber channel parameters      
10 text No Viber Message text.
▪Text requirements – up to 1000 characters (Cyrillic and Latin).
11 ttl Yes Message lifetime in seconds:
▪Viber: 40..86400
12 device No Selection of devices for delivery Messages (only for Viber ID 1way).
▪”all” - delivery to all devices;
▪”phone” - delivery only to smartphones.
If this parameter is not specified, then the parameter takes the value from the settings on CPaaS web-interface.
13 alpha_name No Value of field alpha_name specifies Viber service. Link of alpha_name to Viber service is set on GMS side.
14 img No URL of an image on the Internet.
▪Maximum length: 256 characters.
15 caption No Name of caption.
▪Maximum length:30 characters.
16 action No URL inside the button. Maximum length: 256 characters. You can utilize this if you wish to direct a User to the following:
▪Direct a User to the Web page:”http://example.com”
▪Start Viber call. Opens the Viber keypad with the phone number that you entered in the request:”viber://keypad?number=380961111111”
▪Start a call. Opens the phone number, that you entered in the request:”tel:+380961111111”
▪Open a 1on1 chat -Opens a 1on1 chat with the sender (the sender needs to have a 2way account):”viber://chat?service=3016”
▪Open Viber QR scanner. Opens a QR scanner through Viber. Tapping the button will open the camera to capture a QR code:”viber://more/qr”
SMS channel parameters      
17 text Yes SMS Message text.
▪Text requirements - Cyrillic characters (up to 335 characters), Latin characters (up to 765 characters)
18 ttl Yes Message lifetime in seconds:
▪SMS: 300..259200
19 alpha_name Yes Alphanumeric name.
▪Maximum length is 11 characters, may begin with a number.
▪Alphanumeric name may consist of GSM 7 bit default alphabet table characters only
WhatsApp channel parameters      
20 text No WhatsApp Message text.
▪Text requirements – up to 1000 characters (Cyrillic and Latin)
21 ttl Yes Message lifetime in seconds:
▪WhatsApp: 604800
22 img No URL of an image on the Internet.
▪Maximum length: 256 characters
23 img_name No Text under the image.
▪Maximum length: 1000 characters
24 doc No URL of a file on the Internet.
▪Maximum length: 256 characters
25 doc_name No Text under the file.
▪Maximum length: 1000 characters
26 audio No URL of an audio on the Internet.
▪Maximum length: 256 characters
27 video No URL of a video on the Internet.
▪Maximum length: 256 characters
28 video_name No Text under the video.
▪Maximum length: 1000 characters
29 latitude No Latitude coordinates.
▪Numeric value from -90 to 90
30 longitude No Longitude coordinates.
▪Numeric value from 0 to 180
Pushchannel parameters      
31 text Yes Push Message text.
▪Text requirements – up to 1000 characters (Cyrillic and Latin)
32 ttl Yes Message lifetime in seconds:
▪Push: 30..86400
33 title Yes Title of Message.
▪Maximum length: 20 characters
34 img No URL of an image on the Internet.
▪Maximum length: 256 characters
35 caption No Name of caption.
▪Maximum length: 30 characters
36 action No URL inside the button.
▪Maximum length: 256 characters

Description of the response parameters

Name Description
1 message_id Message identifier.
▪Set in UUID format
2 phone_number User’s phone number.
▪It is given in the international format without the «+» sign
3 extra_id External identifier of the Message (specified by you).
4 job_id Campaign identifier.
▪Set in UUID format
5 error_code Error code.
▪The list of codes is provided in the Statuses section
6 error_text Short description of the error code.
7 processed Boolean value (true/false).
▪It is “true” only if the Message is being processed
▪It is “false” if processing of the Message has not been started
8 accepted Boolean value (true/false).
▪It is “true” only if the Message is accepted by platform
▪It is “false” if the Message is rejected by platform

Description of Message delivery report parameters

Name Description
1 number
phone number
User’s phone number.
▪It is given in the international format without the «+» sign
2 time Unix time stamp for the last action of a communication channel.
3 message_id Message identifier.
4 extra_id External identifier of the Message (specified by you).
5 status Simplified status of the Message.
▪The list of statuses is provided in the Statuses section
6 substatus Extended Message status.
▪The list of statuses is provided in the Statuses section
7 hyber_status Detailed Message status.
▪The list of statuses is provided in the Statuses section
8 sent_via The last channel of Message delivery.
▪If Message is blocked by the Platform – the value of the field is “hyber”
9 total_sms_parts The total number of parts of the SMS-Message.
10 delivered_sms_parts Number of delivered parts of SMS-Message.
▪If there is no Message sent to SMS channel, this parameter is missing
11 matching_template_id Matching Template ID, which specifies the Viber template number.
▪If the Message does not match any template - the value in this field is 0
12 status_text Short description of the status of the Message.
13 error_text Short description of the error.
14 error_code Error code.
▪The list of codes is provided in the Statuses section
15 processed Boolean value (true/false).
▪It is “true” only if the Message is being processed
▪It is “false” if processing of the Message has not been started
16 accepted Boolean value(true/false).
▪It is “true” only if the Message is accepted by platform
▪It is “false” if the Message is rejected by platform
17 last_partner The last channel of Message delivery.
▪If the Message is accepted but has not got final status or it is blocked by the Platform – the value of the field is “hyber”
▪For a detailed report (advanced), this parameter is specified for each communication channel
18 delivered_via The last channel of Message delivery.
▪If the Message is accepted but has not got final status or it is blocked by the Platform – the value of the field is “hyber”
19 started Boolean value (true/false).
▪It is “false” if processing of the Message either has not started or started with delay
20 processing Boolean value (true/false).
▪It is “true” only if the Message is being processed
▪It is “false” if processing of the Message either has not been started or already ended
21 channel Message sending channel.
22 ttl Message lifetime in seconds for each of channels.

Description of User reply parameters

Name Description
1 phone User’s phone number.
▪It is given in the international format without the «+» sign
2 time User’s reply date and time.
▪According to Kyiv local time for Viber User replies
▪UTC+0 for WhatsApp User replies
3 channel The communication channel
4 message_id The Message identifier to which the User replies.
▪Set in UUID format
5 extra_id External identifier of the Message to which the User replies
6 text_to_subscriber Text of Message, to which the User replies
7 text_from_subscriber User’s text reply.
8 umid Transport ID of the sent Message, to which the User replies.
▪Set in UUID format
9 image_url Link of shared image.
▪For example: “https://example.com/image.png”
10 video_url Link of shared video.
▪For example: “https://example.com/video.mp4”
11 audio_url Link of shared audio.
▪For example: “https://example.com/audio.mp3”
12 doc_url Link of shared file.
▪For example: “https://example.com/file.docx”
13 location Link of shared location.
▪For example:”50.450248718262,30.523889541626”