HTTPS API v2 / Sending RCS messages

Calling address

In order to send an RCS message using the Remote Service, you must send a specific application via HTTP or HTTPS using the POST method.

messages/send_rcs

Available parameters

Parameter	Type	An example value or format	Description
username	String	login	Username used to dispatch the message.
password	String	haslo	Password to the account.
rcs_id	String	ID RCS for example: 54c53be2-cbb8-11ec-9d64-0242ac120002	The ID is available in our panel, assigned to each BOT configuration created.
phone	String\|Array	+48500600700	Number or array phones numbers.
message	Array	[]	RCS message structure in Array form.
details	Boolean	true, false or empty	The parameter displays in response to feedback details sent messages.
date	DateTime	ISO for example: „2015-02-22 12:25:55”	An optional parameter allows you to specify the date of dispatch messages.
unique_id	String\|Array	for example: 6asTD3fif98gj	An optional parameter allows you to define your own ID sent message. The identifier can be a minimum of 3 characters and a maximum of 50 alphanumeric characters (a-z, A-Z, 0-9). For group mailings, another unique_id must be unique and the number unique_id must be consistent with the amount of numbers.
group_id	String\|Array	for example: 123456789	ID or group IDs in the Customer Panel. These identifiers can be downloaded using action groups / index or by copying them from the editing group in the Customer Panel.

The parameters marked in bold are mandatory. The others are optional.

Available message structures

1. Text message

{ "text":"Text example", "suggestions":[] }

2. File/image/video message

{ "file":{ "name":"Filename", "url":"https://path_to_file", "type":"video/mp4", "size":1489039 }, "suggestions":[] }

3. Message information card (single)

4. Message information card (carousel)

{ "richcard":[{ "title":"RCS", "description":"Description", "media": { "url":"https://path_to_file", "size":26802, "type":"image/png", "thumbnail":"https://path_to_mini_image", "thumbnailSize":2802, "thumbnailType":"image/jpeg", "height":"SHORT|MEDIUM|TALL" }, "suggestions":[] }, { "title":"RCS", "description":"Description", "media": { "url":"https://path_to_file", "size":26802, "type":"image/png", "thumbnail":"https://path_to_mini_image", "thumbnailSize":2802, "thumbnailType":"image/jpeg", "height":"SHORT|MEDIUM|TALL" }, "suggestions":[] }], "cardWidth":"SMALL|MEDIUM", "suggestions":[] }

When using the 'media' structure, the 'url', 'size' and 'type' elements are required. Below is a list of supported media types:

Type	Typ of document	Extension	Works with information cards
application/ogg	Audio OGG	.ogx	No
application/pdf	PDF	.pdf	No
audio/aac	Audio AAC	.aac	No
audio/mp3	Audio MP3	.mp3	No
audio/mpeg	Audio MPEG	.mpeg	No
audio/mpg	Audio MPG	.mp3	No
audio/mp4	Audio MP4	.mp4	No
audio/mp4-latm	Audio MP4-latm	.mp4	No
audio/3gpp	Audio 3GPP	.3gp	No
image/jpeg	JPEG	.jpeg, .jpg	Yes
image/gif	GIF	.gif	Yes
image/png	PNG	.png	Yes
video/h263	Video H263	.h263	Yes
video/m4v	Video M4V	.m4v	Yes
video/mp4	Video MP4	.mp4	Yes
video/mpeg4	Video MPEG-4	.mp4, .m4p	Yes
video/mpeg	MPEG-video	.mpeg	Yes
video/webm	Video WEBM	.webm	Yes

Suggestions

The suggestion element is not required, but it allows you to add additional buttons that allow you to, among other things, redirect the user to a website, make a call, direct you to an e-mail address or send a reply message. We have four options at our disposal: 'url', 'dial', 'map', 'calendar' and the 'to' parameter corresponds to the value, e.g. for the 'url' type it will be the URL, for 'dial' the telephone number, ' map' coordinates, and 'calendar' information about the event.

Possible structures are presented below:

[ { "reply":{ "text":"Label", "postback":"uslugi", } }, { "action":{ "text":"Label", "postback":"my_url", "action":"url", "to":"https://adres_url_do_przekierowania", } }, { "action":{ "text":"Label", "postback":"my_dial", "action":"dial", "to":"+48100100100", } }, { "action":{ "text":"Label", "postback":"my_map", "action":"map", "to":"SerwerSMS|50.0904966|18.5803288", } }, { "action":{ "text":"Label", "postback":"my_calendar", "action":"calendar", "to":"2022-04-05 09:00:00|2022-04-05-10:00:00|Wydarzenie", } } ]

The string of characters contained in the array under the 'postback' key identifies the event, which will then be transferred in the form of PUSH to the defined Webhook URL address. In this way, you can implement an automatic response scenario in response to appropriate user behavior. The maximum number of characters identifying the button content ('text' field) is 25.

Depending on the data sent, SerwerSMS.pl will generate in response a document in JSON/XML format with information on the actions performed. Thus, if the SMS message is sent correctly, the customer will receive, for example, the following information:

{ "success":true, "queued":1, "unsent":0 }

If an additional parameter details=true is provided, the return response will be supplemented with details of the sent messages, which can be saved in the database on the client software side:

{ "success":true, "queued":1, "unsent":0, "items":[{ "id":"1c142d81c7", "phone":"+48500600700", "status":"queued", "queued":"2014-10-16 16:49:05", "text":"Test SerwerSMS.pl" }] }

The "success" parameter contains information about the success of the operation. The "queued" and "unset" attributes contain the numbers of queued and unsent messages. The "items" section contains phone numbers and IDs of messages submitted for sending (and messages that were not queued for a specific reason). The unique SMS message tag can later be used to remotely check the sending status of a specific SMS message. The "text" parameter contains the content of the SMS message being sent. The telephone number is automatically corrected and displayed in the full format required by SerwerSMS.pl, i.e. with the country code (e.g. +48) at the beginning.

In addition, a general error may be generated where there is no distinction between queued and incorrect. This may occur, for example, when the customer does not define the content of the message, does not provide telephone numbers, his account is not active or another problem described in the error messages occurs. If the appropriate permission is not available, the following message will be generated:

{ "error":{ "code":6300, "type":"RcsError", "message":"You do not have permission to send messages" } }

Error messages

Kod błędu	Opis
6300	You do not have permission to send messages
6301	Invalid BOT ID or configuration is inactive
6302	The message structure is incorrect
6303	No required parameters
6304	Invalid IP address
6306	Invalid phone number
6307	Empty message structure
6308	Set the selected message type (text, audio, file, richcard)
6309	The suggestion structure is incorrect
6310	The message body is empty
6311	Audio message structure is invalid or missing required parameters (name, file)
6312	File message structure is incorrect or required parameters are missing (name, url, mime, size)
6313	File message structure is invalid Richcard message structure is invalid or missing required parameters (title, description, media) or missing required parameters (name, url, mime, size)
6314	The Map message structure is invalid
6315	Overall error
6317	Network not supported

URL notifications

A URL notification is sent to the Webhook address specified in the panel (during BOT configuration), which defines the report, the user's response action (e.g. clicking on the selected suggestion) or the user's entered response. There are three basic structures, distinguished by the 'type' field: 'report', 'reply', 'action' and 'message'. Data is sent using the POST method in the form of a JSON structure. The notification is sent from the IP address 94.152.153.158.

Structure for the 'report' notification (status of the sent RCS message):

[{ "type":"report", "status":"displayed", "smsid":"7HydhfmN", "rcs_id":"c6dyuf34-abYh-oPlo-jusYqPl9IkNs", "phone":"+48100100100", "date":"2022-05-04 16:55:45" }]

Structure for 'reply' or 'action' notification (event performed by the user):

[{ "type":"reply|action", "data":"my_service", "text":"U2VydmljZQ==", "rcs_id":"c6dyuf34-aauh-1dkj-dhfbbtldngh1", "phone":"+48100100100", "msgid":"Mx1j==djUhfjHfkghNfhg", "date":"2022-05-04 16:55:45" }]

Structure for the 'message' notification (message sent back by the user):

[{ "type":"message", "text":"VGV4dCBtZXNzYWdl", "rcs_id":"c6dyuf34-aauh-1dkj-dhfbbtldngh1", "phone":"+48100100100", "msgid":"AMx1jdjUfhfjHfkghNfhg", "date":"2022-05-04 16:55:45" }]

In the customer panel, you can specify the correct answer tag for the selected configuration. If a string of characters has been entered, the mechanism will expect a matching response, otherwise it will repeat the request every 30 minutes until a maximum of 5 attempts is achieved.

The information contained in the 'text' element is encoded in base64 form.

Recommended settings

In the case of medium and large amounts of sent messages of several thousand or more, it is recommended to send messages in "packs" of about 50 numbers in one query. This will significantly speed up the process of transferring data to SerwerSMS.pl and reduce the number of queries necessary to send.