Sending Free Form Messages

Check different types of messages you can send to your customer once they've sent you a message.

For sending OMNI messages, you can use the advanced API method. Detailed descriptions of the advanced API method can be found here: OMNI:// Send an advanced message.

The parameters that should be set are the scenario key, phoneNumber and specific text for each communication channel, as shown below.

WhatsApp allows formatting in messages. To format all or part of a message, use following formatting symbols:

Formatting	Symbol	Example
Bold	Asterisk (*)	Your total is $10.50.
Italics	Underscore (_)	Welcome to _WhatsApp_!
~~Strikethrough~~	Tilde (~)	This is ~better~ best!
Code	Three backticks (```)	```print 'Hello World';```

Emojis can be inserted in the message text.

WHATSAPP SESSIONS

To send any messages other than template message, the user needs to initiate a session by sending a message towards the enterprise. The session is established for 24 hours and it’s called Customer Care Window. With every new message from end-user, Customer Care Window is being renewed. Only template messages can be sent without establishing Customer Care Window.

Send text free form messages

JSON

POST /omni/1/advanced HTTP/1.1 
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {
        "text": "This WhatsApp message will be delivered to WhatsApp application on the user device."
    },
    "sms": {
        "text": "This is the SMS failover message"
    }
}

Response format

If successful, the response header HTTP status code will be 200 OK and the message will be sent.

If you try to send the message without authorization, you will receive a 401 Unauthorized error.

JSON

HTTP/1.1 200 OK 
Content-Type: application/json 
 
{
    "messages": [
        {
            "to": {
                "phoneNumber": "41793026731"
            },
            "status": {
                "groupId": 1,
                "groupName": "PENDING",
                "id": 7,
                "name": "PENDING_ENROUTE",
                "description": "Message sent to next instance"
            },
            "messageId": "50c24400-124f-4678-9f4b-309e994a4deb"
        }
    ]
}

Send WhatsApp Image message

If you would like to send WhatsApp messages containing text and image, please check the example provided below.

Parameter	Type	Description
text	`string`	Text of the message that will be sent. Max 3000 characters.
imageUrl	string	URL of the image sent in the WhatsApp message. Max 800 characters.

One additional parameter could be specified prior to sending the message:

Name	Required	Description
previewUrl	No	Options: false (default), true Specifying previewUrl in the request is optional when not including a URL in your message. To include a URL preview, set previewUrl to true in the message body and make sure that URL begins with http:// or https://

Supported image types are JPG, JPEG, PNG.

WHATSAPP IMAGE MESSAGE

When sending WhatsApp image message, imageUrl is mandatory!

Image WhatsApp message request example:

JSON

POST /omni/1/advanced HTTP/1.1 
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {
        "text": "Get your message across!",
        "imageUrl": "https://www.infobip.com/infobip-logo.png"
    },
    "sms": {
        "text": "This text will be received via SMS if WhatsApp message is not delivered.",
        "validityPeriod": 1
    }
}

Send WhatsApp Audio message

If you would like to send WhatsApp messages containing an audio file, please check the example provided below.

Parameter	Type	Description
audioUrl	`string`	URL of the audio file sent in the WhatsApp message. Max 800 characters.

Supported audio types are AAC, M4A, AMR, MP3, OGG, OPUS.

WHATSAPP AUDIO MESSAGE

When sending WhatsApp audio message, audioUrl is mandatory!

Audio WhatsApp message request example:

JSON

POST /omni/1/advanced HTTP/1.1 
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {
        "audioUrl": "https://www.audioUrl.com"
    },
    "sms": {
        "text": "This text will be received if WhatsApp communication channel message is not delivered."
    }
}

Send WhatsApp Video message

If you would like to send WhatsApp messages containing a video file, please check the example provided below.

Parameter	Type	Description
text	string	Text of the message that will be sent. Max 3000 characters.
videoUrl	string	URL of the video sent in the WhatsApp message. Max 800 characters.

Supported video types are MP4, 3GPP.

Note: Only H.264 video codec and AAC audio codec is supported.

WHATSAPP VIDEO MESSAGE

When sending WhatsApp video message, videoUrl is mandatory!

Video WhatsApp message request example:

JSON

POST /omni/1/advanced HTTP/1.1 
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {        
        "text": "Get your message across!",
        "videoUrl": "https://www.infobip.com/video.mp4"
    },
    "sms": {
        "text": "This text will be received if WhatsApp communication channel message is not delivered."
    }
}

Send WhatsApp Document message

If you would like to send WhatsApp messages containing document file, please check the example provided below.

Parameter	Type	Description
text	`string`	Name of the file that will be sent. Max 240 characters.
fileUrl	string	URL of the file sent in the WhatsApp message. Max 800 characters.

Supported document types are PDF, DOC(X), PPT(X), XLS(X).

WHATSAPP DOCUMENT MESSAGE

When sending WhatsApp document message, fileUrl is mandatory!

Document WhatsApp message request example:

JSON

POST /omni/1/advanced HTTP/1.1 
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {
        "text": "File caption",
        "fileUrl": "https://www.documentUrl.com"
    },
    "sms": {
        "text": "This text will be received if WhatsApp communication channel message is not delivered."
    }
}

Send WhatsApp Location message

If you would like to send WhatsApp location message, please check the example provided below.

Parameters

Body Params

Parameter	Type	Description
longitude	double	Longitude of a coordinate. The value must be between -180 and 180
latitude	double	Latitude of a coordinate. The value must be between -90 and 90.
locationName	string	Name of the location. Optional value.
address	string	Address location. Optional value.

WHATSAPP LOCATION MESSAGE

When sending WhatsApp location message, longitude and latitude are mandatory!

Location WhatsApp message request example:

JSON

POST /omni/1/advanced HTTP/1.1 
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {
        "longitude": 15.946519,
        "latitude": 45.793337,
        "locationName": "Name of the location",
        "address": "Address name"
    },
    "sms": {
        "text": "This text will be received if WhatsApp communication channel message is not delivered."
    }
}

Send WhatsApp Contact message

Contact message consists of an array of contact object. Each contact object consists of several objects, of which name object is mandatory and others are optional.

Parameter	Type	Description
name	object	Contains information about the name and last of a contact.
addresses	array of objects	Address information.
emails	array of objects	Email information.
org	object	Company information.
phones	array of objects	Phone information.
urls	array of objects	Url information.
birthday	string	Birthday information, YYYY-MM-DD formatted string.

Name

Parameter	Type	Description
firstName	string	First name of a contact. Mandatory value.
formattedName	string	Full name as it normally appears. Mandatory value.
lastName	string	Last name of a contact.
middleName	string	Middle name of a contact.
nameSuffix	string	Name suffix of a contact.
namePrefix	string	Name prefix of a contact.

Addresses

Parameter	Type	Description
street	string	Street name.
city	string	City name.
state	string	State name.
zip	string	Zip value.
country	string	Country name.
countryCode	string	Country code value.
type	string	Type of an address. Can be HOME, WORK.

Emails

Parameter	Type	Description
email	string	Email of a contact.
type	string	Type of an email. Can be HOME, WORK

Phones

Parameter	Type	Description
phone	string	Phone of contact.
waId	string	WhatsApp ID.
type	string	Type of a phone. Can be CELL, MAIN, IPHONE, HOME, WORK.

URLs

Parameter	Type	Contact
url	string	Url of a contact.
type	string	Type of a url. Can be HOME, WORK

org

Parameter	Type	Description
company	string	Company name

Document WhatsApp contact request example:

JSON

POST /omni/1/advanced HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
	"scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
	"destinations": [{
		"to": {
			"phoneNumber": "41793026727"
		}
	}],
	 "whatsApp": {
                   "contacts":[{
                          "addresses": [
                              {
                                   "city": "Zagreb",
                                   "country": "Croatia",
                                   "countryCode": "1111",
                                   "street": "Zadarska",
                                   "type": "WORK",
                                   "zip": "1111"
                               }
                           ],
                           "birthday": "2016-01-01",
                           "emails": [
                               {
                                   "email": "infobip@infobip.com",
                                   "type": "WORK"
                               }
                           ],
                           "name": {
                               "firstName": "First Name",
                               "formattedName": "Formatted Name",
                               "lastName": "Last Name"
                           },
                           "org": {
                               "company": "Infobip"
                           },
                           "phones": [
                               {
                                   "phone": "41793026727",
                                   "type": "WORK",
                                   "waId": "1111"
                               }
                           ],
                           "urls": [
                               {
                                   "url": "https://dev.infobip.com/omni-channel/omni-whatsapp-example",
                                   "type": "WORK"
                               }
                           ]}]
                  },
	"sms": {
		"text": "This text will be received if WhatsApp communication channel message is not delivered."
	}
}

Delete media from the cache

Any media that is sent with free form messages is saved in cache for 30 days. In order to delete it from the cache, the request below should be used.

JSON

DELETE /whatsapp/1/senders/{whatsapp_sender}/media HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
{
“url”:”{url_to_delete}”
}

Prev: Incoming WhatsApp messages