Categories:
Start a conversation in RCS channel
Sending messages through aura push
Introduction
Due to the design of the RCS protocol, the conversation with the user must be started by the server, who always sends the first message. To send this first message or other
messages without being in a conversation, the plugin aura push is used.
Sending text messages to the user
To send a simple text message to the user, a body like the following should be sent to the aura push endpoint:
{
"url":"https://svc-ap-next.auracognitive.com/aura-services/v1/aurapush/messages?channelId=f7fd1021-41cd-588a-a461-387cc24be225&apikey=XXX",
"channelId":"f7fd1021-41cd-588a-a461-387cc24be225",
"from":"+34666666666",
"id":"a1be40d0-b8de-4c2a-8a26-8740a739675e",
"text":"Hi! I'm Aura",
"type":"rcs",
"notificationId":"a1be40d0-b8de-4c2a-8a26-8740a739675e",
"notificationType":"not declared",
"checkContact":true
}
Sending complex messages to the user
If you need to send a more complex RCS message to the user, like a file, a card or any other type of RCS message, you need to add the rcsContentMessage field, that corresponds
with the contentMessage field of RCS messages:
{
"url":"https://svc-ap-next.auracognitive.com/aura-services/v1/aurapush/messages?channelId=f7fd1021-41cd-588a-a461-387cc24be225&apikey=XXX",
"channelId":"f7fd1021-41cd-588a-a461-387cc24be225",
"from":"34666666666",
"id":"a1be40d0-b8de-4c2a-8a26-8740a739675e",
"text":"This text will be ignored",
"type":"rcs",
"notificationId":"a1be40d0-b8de-4c2a-8a26-8740a739675e",
"notificationType":"not declared",
"checkContact":true,
"rcsContentMessage": {
"contentInfo": {
"fileUrl": "https://media.tenor.com/3VSWB_GIkqwAAAAe/wololo-age-of-empires.png",
"forceRefresh": "false"
}
}
}
Also, if you want to send all the messages in the same way, text messages can be sent with this format:
{
"url":"https://svc-ap-next.auracognitive.com/aura-services/v1/aurapush/messages?channelId=f7fd1021-41cd-588a-a461-387cc24be225&apikey=XXX",
"channelId":"f7fd1021-41cd-588a-a461-387cc24be225",
"from":"34666666666",
"id":"a1be40d0-b8de-4c2a-8a26-8740a739675e",
"text":"This text will be ignored",
"type":"rcs",
"notificationId":"a1be40d0-b8de-4c2a-8a26-8740a739675e",
"notificationType":"not declared",
"checkContact":true,
"rcsContentMessage": {
"text": "Hi! I'm Aura"
}
}
Sending messages through aura-bot
The previous messages are sent directly from aura-bridge to the user, but if you need to send a more complex message with data that can only be accessed by a bot dialog, you
can send a message to a bot dialog setting the type field to directline-rcs like this:
{
"url":"https://svc-ap-next.auracognitive.com/aura-services/v1/aurapush/messages?channelId=f7fd1021-41cd-588a-a461-387cc24be225&apikey=XXX",
"channelId":"f7fd1021-41cd-588a-a461-387cc24be225",
"from":"34666666666",
"id":"a1be40d0-b8de-4c2a-8a26-8740a739675e",
"text":"{\"intent\": \"intent.rcs.template\"}",
"type":"directline-rcs",
"notificationData":{
"brand":"Vivo",
"anotherCustomParam": "anotherCustomValue"
},
"notificationId":"a1be40d0-b8de-4c2a-8a26-8740a739675e",
"notificationType":"not declared",
"checkContact":true,
"rcsContentMessage": {
"text": "Hi {{customerName}}! I'm Aura, the AI assistant from {{brand}}"
}
}
Sending a message like the previous example, the bot will receive an activity like this, with the fields notificationData,
rcsContentMessage, uuid, notificationType and notificationId forwarded inside the channelData.payload.bridge.customData
field of the activity:
{
"type": "message",
"id": "d152aee9-1aaa-5b54-95a5-79352eee2e45|a1be40d0-b8de-4c2a-8a26-8740a739675e",
"channelId": "f7fd1021-41cd-588a-a461-387cc24be225",
"from": {
"id": "34666666666",
"name": "javiagent_crbwyhqz_agent"
},
"conversation": {
"id": "1f6b5e0e-a5e1-4567-a39d-ba239d7d6d14"
},
"channelData": {
"version": "3",
"appContext": {
"channel": {
"modality": "text",
"id": "f7fd1021-41cd-588a-a461-387cc24be225"
},
"timestamp": "2024-10-14T13:40:54+02:00",
"timezone": "Europe/Madrid"
},
"payload": {
"bridge": {
"customData": {
"uuid": "a1be40d0-b8de-4c2a-8a26-8740a739675e",
"notificationType": "not declared",
"notificationId": "a1be40d0-b8de-4c2a-8a26-8740a739675e",
"notificationData": {
"brand":"Vivo",
"anotherCustomParam": "anotherCustomValue"
},
"rcsContentMessage": {
"text": "Hi {{customerName}}! I'm Aura, the AI assistant from {{brand}}"
}
}
},
"auraGroot": {
"channelConversationId": "d152aee9-1aaa-5b54-95a5-79352eee2e45",
"channelId": "f7fd1021-41cd-588a-a461-387cc24be225"
}
},
"correlator": "078ee5cf-2b9d-4fb6-9268-c9c5685232f8"
},
"text": "{\\"intent\\": \\"intent.rcs.template\\"}",
"serviceUrl": "http://localhost:8080/api/skills",
"relatesTo": {
"serviceUrl": "http://localhost:8045/aura-services/javiagent",
"activityId": "d152aee9-1aaa-5b54-95a5-79352eee2e45|a1be40d0-b8de-4c2a-8a26-8740a739675e",
"channelId": "f7fd1021-41cd-588a-a461-387cc24be225",
"conversation": {
"id": "d152aee9-1aaa-5b54-95a5-79352eee2e45"
},
"bot": null
},
"recipient": {
"role": "skill"
},
"callerId": "urn:botframework:aadappid:3837ac07-50e0-4d4e-993b-1bda1349f25a",
"locale": "es-cr"
}
With this data you can create your custom dialog. The easiest way to reach your dialog is sending an aura-command with the desired intent in the text field as you have seen in the previous example.
In the rcsContentMessage you can send your pre-formated RCS body to be filled by the bot, and if you need more extra params can be sent in the notificationData field.
Checking the contact availability
RCS is enabled in Android since version 5, and in iOS since version 18, but some customers couldn’t have it disabled or not available in their phones. To avoid errors
sending messages to phones that doesn’t allow RCS, you can check with the api if this phone is available, and then, send the message. To do this check, the field checkContact
should be sent to true. Take into account that this extra call consumes time, so if you have a list of already available RCS phones, you can skip this step.
If checkContact is set to true and the api returns an error because this phone doesn’t allow RCS, an error 403 will be returned.
Aura line api
You can send a text message directly to the user using the aura push endpoint /aura-services/v1/aurapush/messages.
All the information about the aura push endpoint could be found in the bridge swagger file: