Sending Messages

Use this method to send messages to your clients via edna API.

You can test sending messages to a test phone number using edna API for the WhatsApp channel without having to register your channel first. To do that, go the the Testing tab on the Integration page.
If you want to test sending messages, keep in mind that we check for duplicates in SMS and IM. You cannot send a duplicate message within 20 minutes. Duplicate messages will be canceled.

schedule Method

A completed request using the schedule method results in a message that is sent to the messenger according to the parameters specified in the request body. If the request is successful, the server returns code 200 with a JSON object detailing the message identifier and its sending status. If the request fails, the server returns a response with an error code.

URL

To send a message, a POST request is sent to the following URL address:  https://app.edna.io/api/cascade/schedule

Request Format

A JSON object is passed in the request body with all the cascade and message parameters. These parameters depend on the message type and its contents.

Request Example

Below is an example of a request body that uses a cascade as follows: first, a message is sent to the client via the push channel, then – to the client’s WhatsApp, and finally – via the SMS channel.

{
    "requestId": "test-001",
    "cascadeId": 111,
    "subscriberFilter": {
        "address": "79000000000",
        "type": "PHONE"
    },
    "startTime": "2022-01-21T08:00:00Z",
    "content": {
        "smsContent": {
            "text": "The card is ready. You can pick it up at the bank office"
        },
        "whatsappContent": {
            "contentType": "TEXT",
            "text": "The card is ready. You can pick it up at the bank office",
            "attachment": {
                "url": "https://.jpg",
                "name": "How to find us",
                "size": 5123
            },
            "location": {
                "longitude": 56.7645,
                "latitude": 48.4564,
                "address": "Moscow, ul. Pravdy 3"
            }
        },
        "pushContent": {
            "small": {
                "text": "You can pick it up at the bank office",
                "title": "The card is ready",
                "imageUrl": "https://.png"
            },
            "big": {
                "title": "The card is ready",
                "text": "You can pick it up at the bank office",
                "imageUrl": "https://.png"
            },
            "buttons": [
                {
                    "text": "Contact support",
                    "url": "DeeplinkSupport"
                },
                {
                    "text": "Remind me later",
                    "url": "DeeplinkLater"
                }
            ],
            "action": "DeeplinkMainPush",
            "effects": {
                "vibrate": "[500,100,500,150,50,50]",
                "lights": "#770808",
                "sound": "AthlonRoar",
                "androidNotificationChannel": "Order status"
            },
            "iosSettings": {
                "interruptionLevel": "ACTIVE",
                "category": "ednaPushCategory"
            }
        }
    }
}

Request Parameters

Below are tables with a full set of parameters, their types, and descriptions. Examples of requests for each channel and content type are available here.

General Parameters

ParameterData typeDescription
requestIdstringMessage identifier. It is generated by your system, after which the value must be transferred to the request. Any length of the string up to 36 characters is allowed.
cascadeIdstringCascade identifier. When you create a channel, it also automatically creates a cascade for sending messages via this channel. To retrieve the ID of the required cascade, use the API method for retrieving cascade information (refer to the id parameter).
subscriberFilterstringRecipient of the message: a client’s ID in edna Platform, their phone number or their Instagram ID.

subscriberFilter consists of the following parameters: address and typeConsequently, type can be IDPHONE, and INSTAGRAM_ID, and address is the value depending on the type (so, for example, if type is PHONEaddress will be the client’s phone number). Example:

"subscriberFilter":
{
"address": "79000000000",
"type": "PHONE"
},
addressstringValue depending on type
typestringType of the client’s identifier: ID or PHONE
EDNA_IDstringClient’s identifier in edna Platform database. It is generated automatically when you create/upload a client to the system. The identifier is displayed in the URL on the Edit client page, for example, 3314 in https://app.edna.ru/audience/3314/edit
PHONEstringClient’s phone number
INSTAGRAM_IDstringClient’s 16-digit identifier in Instagram. It is generated automatically by Meta when the client contacts the company’s Instagram business account. The value can be different and can change for the same Instagram client
DEVICE_APP_IDstringID of the client’s push device
startTimestring (optional)Start time, i.e. the time when the message will be sent (it won’t be sent until the time you specify).

• YYYY-MM-DDTHH:mm:ss.SSSXXX (2021-01-21T08:00:00Z)
• YYYY-MM-DDTHH:mm:ss.SSS+TZ (2021-01-21T08:00:00Z+03:00)
contentobjectObject; can contain the following objects: smsContent, whatsappContent, viberContent

whatsAppContent Parameters

ParameterData typeDescription
contentTypestring
(optional)
Message content type with the following possible values (must be specified in the upper case):

TEXT – Text message
IMAGE – Image
DOCUMENT – Document attached to the message
VIDEO – Message that contains a video
AUDIO – Message that contains an audio
BUTTON – Message that contains a button
LOCATION – Message that contains coordinates, address, and description of a place. The coordinates are converted into a Google Maps snap.
LIST_PICKER – Interactive menu buttons
textstring (optional)Message text
attachmentobject (optional)Contains info about attachments
attachment.urlstringLink to the image/document/video/audio
attachment.namestring
(optional)
Name of the image/document/video/audio
attachment.sizestring
(optional)
Attachment size
commentstring (optional)Text comment in the message. It is displayed in the detailed message report.
headerstring (optional)Message header. You can select one of the following message header types: text, image, document. For a text header, you need to specify the text itself (it can contain one variable), it displays in bold before the message text. For an image/document header, you can specify the link to the image/document respectively.
footerstring (optional)Message subject that is displayed under the message text in a toned-down color.
locationobject (optional)Contains info about the location
location.longitudestringLongitude coordinates
location.latitudestringLatitude coordinates
location.addressstringAddress on the map
buttonsobject (optional)Array of objects each of which defines a button
buttons.buttonTypestring (optional)Button type:
• TEXT — Button text
• URL — URL that opens once the button is tapped
• PHONE — Phone number
• QUICK_REPLY – Quick reply button
• payload — Returns the incoming message

For more details, refer to the examples.
buttons.textstring (optional)Button text. Max length – 20 characters.
listPickerobject (optional)Object for a list of elements. It contains the button parameter and the sections objects.
listPicker.buttonstringName of the button for the interactive list
listPicker.sections
listPicker.sections.titlestringThe title of a section with elements that is displayed to the user
listPicker.sections.items
array of objects
List of item objects
listPicker.sections.items.
identifier
stringEnd-to-end element ID (for the entire message). It will be returned in the client’s response message
listPicker.sections.items.
title
stringElement’s title
listPicker.sections.items.
subtitle
string (optional)Element’s subtitle

viberContent Parameters

ParameterData typeDescription
contentTypestring
(optional)
Message content type with the following possible values (must be specified in the upper case):

• TEXT – Text message
• IMAGE – Image
• DOCUMENT – Document attached to the message
• VIDEO – Message that contains a video
• AUDIO – Message that contains an audio
• BUTTON – Message that contains a button
• LOCATION – Message that contains coordinates, address, and description of a place. The coordinates are converted into a Google Maps snap.
textstring (optional)Message text
headerobject (optional)Message header. You can select one of the following message header types: text, image, document. For a text header, you need to specify the text itself (it can contain one variable), it displays in bold before the message text. For an image/document header, you can specify the link to the image/document respectively.
footerobject (optional)Message subject that is displayed under the message text in a toned-down color.
attachmentobject (optional)Contains info about attachments
attachment.urlstringLink to the image/document/video/audio
attachment.namestring (optional)Name of the image/document/video/audio
attachment.sizestring (optional)Attachment size
locationobject (optional)Contains info about the location
location.longitudestringLongitude coordinates
location.latitudestringLatitude coordinates
location.addressstring (optional)Address on the map
captionstring (optional)Button caption
actionstring (optional)Button URL

smsContent Parameters

ParameterData typeDescription
textstringMessage text

pushContent Parameters

ParameterData typeDescription
smallobjectParameters for displaying collapsed push notifications
small.titlestring
(optional)
Title of a collapsed push notification
small.textstringText of a collapsed push notification
small.imageUrlstring
(optional)
Icon (logo) to display in collapsed push notifications. The recommended aspect ratio is 1×1, the size limit is 1024×1024
bigobject (optional)Parameters for displaying maximized push notifications
big.titlestring (optional)Text of a maximized push notification
big.textstring (optional)Text of a maximised push notification
big.imageUrlstring (optional)A large image for a maximized push. Images with aspect ratios of 2×1 are recommended, where the main visual mass remains when cropped to 1.79×1 and 2.5×1 (Android restrictions)
actionstring (optional)Link that will be passed to the app when a client taps the push notification
buttonsobject (optional)Button display parameters. Up to two buttons can be displayed together with the notification.
buttons.textstring (optional)The button caption. Users will see this caption on the button in the notification.
buttons.urlstring (optional)Button link. It will be passed to the application when the user taps the button
effectsobject (optional)Sound, vibration, notification channel name, and LED flashing color on the client’s device when receiving a push notification
effects.soundstring (optional)The name of the sound file (without the extension). A file with this name must be located in the res/raw directory of an Android application and in the Xcode root directory of an iOS application
effects.lightsstring (optional)LED color the phone blinks with when receiving push notifications (Android only). Some Android smartphones have a signal LED. Using this parameter, you can set the color of the flashing of this LED when receiving a push
effects.vibratestring (optional)The sequence of intervals of inactivity and vibration of the motor when receiving a push notifications (in milliseconds), Android only. The first value is inactivity. For example, with the pattern [300,500,300,500], the device will be inactive for 300 ms, vibrating for 500 ms, inactive again for 300 ms, vibrating for 500.
effects
.androidNotificationChannel
string (optional)The name of the notification channel for Android. Users will see this name in the smartphone settings. You can only change the channel parameters (sound, vibration, and LED color) for new push notification recipients.
iosSettingsobject (optional)Interruption level and the ContentExtension category (iOS only)
iosSettings
.interruptionLevel
string (optional)The interruption level determines the type of notification on iOS 15 and above.
iosSettings.categorystring (optional)The category for calling ContentExtension. The parameter is processed on the iOS side and determines how the extended push is rendered.
attributesobject (optional)Additional push message parameters. A key-value table in JSON

Quatation Marks in Text

Pay attention to how you put words in quotation marks. If you use the single () or double quote () symbols in the message text, make sure to put the backslash (\) symbol before the opening and after the closing quotation mark. See the following example:

Correct:

"text": "Pablo! We are inviting you to our workshop \“Cooking with Tefal\” 11/25/2021 at 1 p.m. Don\'t miss this event! Give us a call: +7 (495) 100-00-00"

or

"text": "Pablo! We are inviting you to our workshop «Cooking with Tefal» on 11/25/2021 at 1 p.m. Don\'t miss this event! Give us a call: +7 (495) 100-00-00"

Incorrect:

"text": "Pablo! We are inviting you to our workshop “Cooking with Tefal” on 11/25/2021 at 1 p.m. Don't miss this event! Give us a call: +7 (495) 100-80-00"

Text Formatting in WhatsApp

WhatsApp allows you to format text inside your messages. Please note, you cannot disable this feature.

  • Italic: Place an underscore on both sides of the text: _text_
  • Bold: Place an asterisk on both sides of the text: *text*
  • Strikethrough: Place a tilde on both sides of the text: ~text~
  • Monospace: Place three backticks on both sides of the text: ```text```

Response Format

The response contains a JSON object with the ID of the sent message and one of the available response codes.

ParameterData typeDescription
requestidstringMessage identifier. It is generated by your system.

Attachment Types

All attachments that you send must comply with the following requirements. Otherwise, the message will not be delivered.

Content typeSupported formatSize, MB
documentAny valid MIME type100
imageimage/jpeg, image/png5
audioaudio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg
codec: opus (NWB) и ACC
16
videovideo/mp4, video/3gpp

Important! Only MPEG 4 and 3GPP with the codec H.264 (MPEG-4 Part 10) and AAC for audio are supported
16

For details on the media attachment formats for WhatsApp, refer to this article.

For Viber, the name of the attached file (attachmentName) cannot exceed 25 characters. For all other messengers, it can be up to 75 characters.
Next Article Examples of Messages for API