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  

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. 

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: 

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: 

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: 

 
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: 

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: 

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:

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."
	}
}