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

This is an example of the body of a request for the following cascade. First, a message is sent to the client via the push channel, then a WhatsApp message is sent, and finally a text is sent via an SMS channel.

{
    "requestId": "test-001",
    "cascadeId": 111,
    "subscriberFilter": {
        "address": "18000000000",
        "type": "PHONE"
    },
    "startTime": "2022-01-21T08:00:00Z",
    "content": {
        "smsContent": {
            "text": "Your card is ready. Pick it up at the bank office."
        },
        "whatsappContent": {
            "contentType": "TEXT",
            "text": "Your card is ready. Pick 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": "London, Buckingham street"
            }
        },
        "pushContent": {
            "small": {
                "text": "Pick it up at the bank office.",
                "title": "Your card is ready",
                "imageUrl": "https://.png"
            },
            "big": {
                "title": "Your card is ready",
                "text": "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 typeRequiredDescription
requestIdstringyesMessage identifier. The value must be generated by your system and sent to the request. The maximum length is 36 characters.
commentstringText comment in the message. This value is displayed in detailed reports.
cascadeIdstringyesCascade 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).
subscriberFilterstringyesRecipient of the message: a client’s ID in edna Pulse, 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"
},
addressstringyesValue depending on type
typestringyesType of the client’s identifier. Enter a value in upper case.

• INSTAGRAM_ID — Client’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.
• FACEBOOK_ID
• DEVICE_APP_ID — ID of the client’s push device.
• EDNA_ID — Client’s identifier in edna Pulse 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.io/audience/3314/edit.
• PHONE — Client’s phone number, for example, “18000000000”
• EMAIL
• UTM
• COOKIE_ID
• TELEGRAM_ID 
• GOOGLE_ID
• APPLE_ID
• YANDEX_ID
• EXT_USER_ID
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)
contentobjectyesObject; can contain the following objects: smsContent, whatsappContent, viberContent

whatsAppContent Parameters

ParameterData typeRequiredDescription
contentTypestringMessage content type. Enter a value in 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
• AUTHENTICATION — authentication message with one-time password button
textstringyes, if contentType = TEXT or AUTHENTICATIONMessage text, if contentType = TEXT.
One-time password, if contentType = AUTHENTICATION.
attachmentobject Contains info about attachments
IMPORTANT! When sending WhatsApp chat message with the attachment the text field is ignored. Only attachment is sent.
attachment.urlstringyes, if attachment object is not emptyLink to the image/document/video/audio
attachment.namestringName of the image/document/video/audio. Maximum length is 70 characters.
attachment.sizestringAttachment size
commentstringText comment in the message. It is displayed in the detailed message report.
headerstringMessage 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.
footerstringMessage subject that is displayed under the message text in a toned-down color.
locationobjectContains info about the location
location.longitudestringyes, if location object is not emptyLongitude coordinates
location.latitudestringyes, if location object is not emptyLatitude coordinates
location.addressstringAddress on the map
buttonsobjectArray of objects each of which defines a button
buttons.typestringButton type:
• URL — URL that opens once the button is tapped
• PHONE — phone number
• QUICK_REPLY – quick reply button
• OTP — one-time password copy button
For more information, see examples.

A message can contain up to three QUICK_REPLY buttons, or up to one of each URL and PHONE buttons. QUICK_REPLY buttons can’t be in a message with other button types. Possible combinations:
QUICK_REPLY
QUICK_REPLY QUICK_REPLY
QUICK_REPLY QUICK_REPLY QUICK_REPLY
URL
PHONE
URL PHONE
buttons.textstringButton text. Max length – 20 characters.
buttons.urlstringURL to open when a client presses the button
buttons.urlPostfixstringDynamic part of URL
buttons.phonestringPhone number to dial when a client presses the button
buttons.payloadstringQuick reply text
listPickerobjectObject for a list of elements. It contains the button parameter and the sections objects.
listPicker.buttonstringyes, if listPicker object is not emptyName of the button for the interactive list
listPicker.sections.titlestringyes, if listPicker object is not emptyThe 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
stringyes, if listPicker object is not emptyEnd-to-end element ID (for the entire message). It will be returned in the client’s response message
listPicker.sections.items.
title
stringyes, if listPicker object is not emptyElement title
listPicker.sections.items.
subtitle
stringElement subtitle
messageMatcherIdintegeryes, if contentType = AUTHENTICATIONIdentifier of the authorization message template for this message

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. Maximum length is 25 characters.
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.