Send WhatsApp over API

Create Scenario

The first step is to create an OMNI scenario. In the OMNI scenario configuration, you need to define the OMNI steps which will be sequentially executed. The key parameters are the Channel and From, respectively identifying the communication channels and senders for each communication channel.

Prerequisites

The connection itself has to be secured either by using BASE64 hash combination of Infobip credentials, API keys or tokens as the most secured and recommended option. In order to enable secure connection towards Infobip, please refer to this guide that contains all the details for enabling authorized connection⁠—Authentication.

For WhatsApp sender (“channel”: “WHATSAPP” flow) you should use the WhatsApp sender provided during the activation process—the phone number in the international format that was activated for you, per example: 385981234567.

INFO

You need to create the scenario only during the initial phase. This step doesn’t need to be completed every time prior to sending the message. Creation of a new scenario is needed if you are adding new channels in a failover approach or changing the sender you will be using.

Read more on how to create an OMNI scenario.

POST /omni/1/scenarios
Host: {base_url} 
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
{
    "name": "My WHATSAPP-SMS scenario",
    "flow": [
        {
            "from": "WhatsAppSender",
            "channel": "WHATSAPP"
        },
        {
            "from": "InfoSMS",
            "channel": "SMS"
        }
    ],
    "default": true
}	

Response format:

If successful, the response header HTTP status code will be 200 OK, and the scenario will be created, as shown in the example below. 

If you try to create the scenario without authorization, you will receive a 401 Unauthorized error. 

{ 
    "key": "CC9F01A5DC7BEE2C2B829D203482A654", 
    "name":"My WHATSAPP-SMS scenario", 
    "flow": [ 
      { 
        "from": "WhatsAppSender", 
        "channel": "WHATSAPP" 
      }, 
      { 
        "from": "InfoSMS", 
        "channel": "SMS" 
      }     
    ], 
    "default": true 
  }	

The key parameter needs to be stored as it will be used when sending the message.

PRO TIP

Check out the "How to create an OMNI scenario" article for more detailed information.

Send Message Templates

If you would like to send WhatsApp message templates, check out the following example:

Parameters:

Parameter

Type

Description

templateName

string

Template name.

templateData

array of strings

Template parameters values ordered as registered in template. 

language

 

The code of the language or locale to use. It needs to be exactly the code with which the template was registered.

policy

 

Language policy the message should follow—DETERMINISTIC or FALLBACK. 

Only the DETERMINISTIC language policy can be used which means that the message template will be delivered in the exact language and locale as asked for. If this policy is not specified in the request, it will be used by default.

The FALLBACK policy is no longer an option.

NOTE

When sending a WhatsApp message template ‘templateName’, ‘templateData’, and ‘language’ are mandatory fields.

To successfully send the message, all parameters need to match. If the message template contains two placeholders, then the template data needs to contain exactly two parameters. Otherwise, the message template will not be created properly on the end user’s device and the message will not be displayed.

NOTE

Pay attention to match the number of parameters in the registered template and the number of parameters specified in the API call.

WhatsApp message template request example:

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {
        "templateName": "template_name",
        "templateData": [
            "Jennifer",
            "$2543.56"
        ],
        "language": "en"
    },
    "sms": {
        "text": "This text will be received via SMS if WhatsApp message is not delivered.",
        "validityPeriod": 1
    }
}

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 HTTP status code.

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 Media Message Templates

NOTE

Note that the feature is still in beta, thus some changes to the API request format might be introduced in the future.

The Media message template usually consists of three sections—HeaderBody, and Footer. The header contains media, while the body is a mandatory textual field. The footer is optional, can only contain static content and is not defined in the API request.

Supported media types are

  • Image
  • Document
  • Video
  • Location

Additional API details per media type are in the table below.

Send Image Message Templates

If you would like to send WhatsApp image message templates, here’s the additional information you need.

Parameters:

Parameter

Type

Description

templateName

 string

Template name.

mediaTemplateData

array of objects

Array of objects in which parameters necessary for successful media message template delivery are defined.

header

object

Object in which media is defined - in this case, image.

imageUrl

string

Image URL sent in the WhatsApp message.

body

object

Object in which message body placeholder values are defined.

placeholders

array of strings

Information for the message body values.

language

 

The code of the language or locale to use. It needs to be exactly the code with which the template was registered with.

NOTE

When sending a WhatsApp image message template ‘templateName’, ‘imageUrl’, ‘placeholders, and ‘language’ are mandatory fields.

To successfully send the message, all parameters need to match and imageUrl needs to be accessible.

If the message template contains two placeholders, then the placeholders need to contain exactly two parameters. Otherwise, the message template will not be created properly on the end-user’s device and the message will not be displayed.

Supported image types: JPG, JPEG, PNG.

Maximum image size is 5MB.

NOTE

Pay attention to set the right number of parameters in the API call in the correct order as required by the media message template type.

Request example for image message template:

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {
        "templateName": "template_name",
        "mediaTemplateData": {
            "header": {
       "imageUrl":"https://www.filehoster.com/E_ticket.jpg"
            },
            "body": {
                "placeholders": ["John","BAW175"]
            }
        },
        "language": "en"
    },
    "sms": {
        "text": "This text will be received via SMS if WhatsApp message is not delivered.",
        "validityPeriod": 1
    }
}

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 404 Unauthorized HTTP status code.

Send Document Message Templates

If you would like to send WhatsApp document message templates, here’s the additional information you need.

Parameters:

Parameter

Type

Description

templateName

 string

Template name.

mediaTemplateData

array of objects

Array of objects in which parameters necessary for successful media message template delivery are defined.

header

object

Object in which media is defined - in this case, document.

documentUrl

string

Document URL sent in the WhatsApp message.

documentFilename

string

Name of the document that will be sent.

body

object

Object in which message body placeholder values are defined.

placeholders

array of strings

Information for the message body values.

language

 

The code of the language or locale to use. It needs to be exactly the code with which the template was registered.

NOTE

When sending a WhatsApp image message template ‘templateName’, ‘documentUrl’, ‘documentFilename’, ‘placeholders, and ‘language’ are mandatory fields.

To successfully send the message, all parameters need to match and documentUrl needs to be accessible.

If the message template contains two placeholders, then the placeholders need to contain exactly two parameters. Otherwise, the message template will not be created properly on the end user’s device and the message will not be displayed.

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

Maximum document size is 100MB.

NOTE

Pay attention to set the right number of parameters in the API call in the correct order as required by the media message template type.

Request example for document message template:

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {
        "templateName": "template_name",
        "mediaTemplateData": {
            "header": {   "documentUrl":"https://www.filehoster.com/receipt_012020.pdf",
"documentFilename":"Invoice_012020"
            },
            "body": {
                "placeholders": ["Peter"," January 2020"]
            }
        },
        "language": "en"
    },
    "sms": {
        "text": "This text will be received via SMS if WhatsApp message is not delivered.",
        "validityPeriod": 1
    }
}

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 404 Unauthorized HTTP status code.

Send Video Message Templates

If you would like to send WhatsApp video message templates, here’s the additional information you need.

Parameters:

Parameter

Type

Description

templateName

 string

Template name.

mediaTemplateData

array of objects

Array of objects in which parameters necessary for successful media message template delivery are defined.

header

object

Object in which media is defined - in this case, video.

videoUrl

string

Video URL sent in the WhatsApp message.

body

object

Object in which message body placeholder values are defined.

placeholders

array of strings

Information for the message body values.

language

 

The code of the language or locale to use. It needs to be exactly the code with which the template was registered.

NOTE

When sending a WhatsApp video message template ‘templateName’, ‘videoUrl’, ‘placeholders, and ‘language’ are mandatory fields.

To successfully send the message, all parameters need to match and videoUrl needs to be accessible.

If the message template contains two placeholders, then the placeholders need to contain exactly two parameters. Otherwise, the message template will not be created properly on the end user’s device and the message will not be displayed.

Supported video types: MP4, 3GPP.

Maximum video size is 16MB.

NOTE

Pay attention to set the right number of parameters in the API call in the correct order as required by the media message template type.

Request example for video message template:

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {
        "templateName": "template_name",
        "mediaTemplateData": {
            "header": {
 "videoUrl":"https://www.filehoster.com/instructions_video.mp4"
            },
            "body": {
                "placeholders": ["Mary","account setup"]
            }
        },
        "language": "en"
    },
    "sms": {
        "text": "This text will be received via SMS if WhatsApp message is not delivered.",
        "validityPeriod": 1
    }
}

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 404 Unauthorized HTTP status code.

Send Location Message Templates

If you would like to send WhatsApp location message templates, here’s the additional information you need.

Parameters:

Parameter

Type

Description

templateName

 string

Template name.

mediaTemplateData

array of objects

Array of objects in which parameters necessary for successful media message template delivery are defined.

header

object

Object in which media is defined - in this case, location.

latitude

number

Latitude of a coordinate. The value must be between -90 and 90.

longitude

number

Longitude of a coordinate. The value must be between -180 and 180

body

object

Object in which message body placeholder values are defined.

placeholders

array of strings

Information for the message body values.

language

 

The code of the language or locale to use. It needs to be exactly the code with which the template was registered.

NOTE

When sending a WhatsApp location message template ‘templateName’, ‘latitude’,’longitude’, ‘placeholders, and ‘language’ are mandatory fields.

To successfully send the message, all parameters need to match.

If the message template contains two placeholders, then the placeholders need to contain exactly two parameters. Otherwise, the message template will not be created properly on the end user’s device and the message will not be displayed. 

NOTE

Pay attention to set the right number of parameters in the API call in the correct order as required by the media message template type.

Request example for location message template:

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 
 
{
    "scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727"
            }
        }
    ],
    "whatsApp": {
        "templateName": "template_name",
        "mediaTemplateData": {
            "header": {
		"latitude": 45.793337,
		"longitude": 15.946519
            },
            "body": {
                "placeholders": ["Jane","ATM"]
            }
        },
        "language": "en"
    },
    "sms": {
        "text": "This text will be received via SMS if WhatsApp message is not delivered.",
        "validityPeriod": 1
    }
}

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 404 Unathorized HTTP status code.

Send Interactive Message Templates

An interactive message template can consist of the Header, Body, Footer, and Bottons sections.

The header is an optional section that contains media or text, while the body is a mandatory textual field. The footer is optional, can only contain static content and is not defined in the API request.

Buttons can be either Quick Reply or Call to Action.

Additional API details per button type are in the table below.

Send Interactive Message Template with Quick Reply Buttons

If you would like to send WhatsApp interactive message templates with Quick Reply buttons, here’s the additional information you need.

Parameters:

Parameter

Type

Description

templateName

 string

Template name.

mediaTemplateData

array of objects

Array of objects in which parameters necessary for successful media message template delivery are defined.

header

object

Object in which header information is defined. Information within the object. Refer to Media message templates API for more info.

Optional - only if defined during template registration

body

object

Object in which message body placeholder values are defined.

placeholders

array of strings

Information for the message body values.

buttons

array of objects

Array of objects in which parameters for each button are defined.

quickReplyPayload

string

Payload for a quick reply button, which will be returned with the incoming message when the button is clicked on.

Max 128 characters.

language

 

The code of the language or locale to use. It needs to be exactly the code with which the template was registered with.

NOTE

When sending a WhatsApp interactive message template with quick reply buttons, buttons, and quickReplyPayload, parameters are mandatory.

To successfully send the message, all parameters need to match.

If the message template contains one placeholder, then the placeholders needs to contain exactly one parameter. Otherwise, the message template will not be created properly on the end-user’s device and the message will not be displayed.

NOTE

quickReplyPayload needs to be defined for each of the buttons and set in the API call in the correct order as defined when the template was registered.

Interactive message template with quick reply buttons request example:

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 

{
  "scenarioKey":"CC9F01A5DC7BEE2C2B829D203482A654",
  "destinations":[
    {
      "to":{
        "phoneNumber": "41793026727"
      }
    }  ],
  "whatsApp": {
    "templateName":"template_name",
    "mediaTemplateData": {
    	"body": {
    		"placeholders": ["Elizabeth"]
    	},
    	"buttons": [{"quickReplyPayload": "CM445-PRO"}, {" quickReplyPayload": " CM445-CON "}, {"quickReplyPayload ": "CM445-MOREINFO"}]
    },
    "language":"en"
  },
  "sms": {
    "text": "This text will be received if WhatsApp communication channel message is not delivered."
  }
}

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 404 Unauthorized HTTP status code.

If an end user responds to the message by clicking on quick reply button, incoming message defined by type “Button”, with information on button text and payload, will be forwarded to your webhook.

Send Interactive Message Template with Call to Action Buttons

If you would like to send WhatsApp interactive message templates with call to action buttons, here’s the additional information you need.

Parameters:

Parameter

Type

Description

templateName

 string

Template name.

mediaTemplateData

array of objects

Array of objects in which parameters necessary for successful media message template delivery are defined.

header

object

Object in which header information is defined. Information within the object. Refer to Media message templates API for more info.

Optional - only if defined during template registration

body

object

Object in which the message body placeholder values are defined.

placeholders

array of strings

Information for the message body values.

buttons

array of objects

Array of objects in which parameters for each button are defined.

urlPlaceholder

string

Placeholder information, which is added as an extension to URL if the URL has been defined as dynamic.

Optional – only mandatory if Visit Website action has been defined with a dynamic URL during template registration.

language

 

The code of the language or locale to use. It needs to be exactly the code with which the template was registered with.

NOTE

When sending a WhatsApp interactive message template with call to action buttons, the buttons parameter is mandatory. If the Visit Website button has been defined with a dynamic URL during template registration, urlPlaceholder parameter is also mandatory.

To successfully send the message, all parameters need to match.

If the message template contains one placeholder, then the placeholders needs to contain exactly one parameter. Otherwise, the message template will not be created properly on the end-user’s device and the message will not be displayed.

Interactive message template with call to action buttons request example:

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json 


{
  "scenarioKey":"CC9F01A5DC7BEE2C2B829D203482A654",
  "destinations":[
    {
      "to":{
        "phoneNumber": "41793026727"
      }
    }  ],
  "whatsApp": {
    "templateName":"template_name",
    "mediaTemplateData": {
    	"body": {
    		"placeholders": ["Nick","489672"]
    	},
    	"buttons": [{"urlPlaceholder": "delivery/London/489672"}]
    },
    "language":"en"
  },
  "sms": {
    "text": "This text will be received if WhatsApp communication channel message is not delivered."
  }
}

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 404 Unauthorized HTTP status code.

Send Free-Form Messages

For sending OMNI messages, you can use the advanced API method.

To send a message to one or more destination addresses, refer to the OMNI: Send and advanced message article.

The parameters you need to set are the “scenario key”, “phoneNumber” and specific text for each communication channel.

WhatsApp allows message formatting. To format each part of your message, use the following markup: 

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 messages other than message templates, the end user needs to initiate a session by sending a message to the enterprise. The session is active for the next 24 hours. This is called the customer care window. Every time the end user sends a message to the enterprise, this customer care window is renewed. Only message templates can be sent without establishing the customer care window.

Request example:

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
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, check the example provided below.

Parameter

Type

Description

text

string

Text of the message that will be sent. Max 3000 characters. 

imageUrl

string

Image URL 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 if you do not include a URL in your message. 


To include a URL preview, set ‘previewUrl’ to TRUE in the message body and make sure that the URL begins with http:// or https://  

Supported image types: JPG, JPEG, PNG. Maximum image size is 5MB

NOTE

When sending a WhatsApp image message, ‘imageUrl’ is mandatory!

Image WhatsApp message request example: 

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
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, check the example provided below. 

Parameter

Type

Description

audioUrl

string

Audio file URL sent in the WhatsApp message. Max 800 characters.  

Supported audio types are AAC, AMR, MP3, OPUS. Maximum audio size is 16MB.

NOTE

When sending WhatsApp audio message, ‘audioUrl’ is mandatory!

Audio WhatsApp message request example: 

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
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, 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. Maximum video size is 16MB.

NOTE

Only H.264 video codec and AAC audio codec are supported. When sending WhatsApp video message, ‘videoUrl’ is mandatory.

Video WhatsApp message request example: 

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
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 a document file, 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). Maximum document size is 100MB.

NOTE

When sending a WhatsApp document message, ‘fileUrl’ is mandatory.

Document WhatsApp message request example: 

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
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."
    }
}

Media Type Size Limitations

Media type

Size

image

5 MB

audio

16 MB

video

16 MB

document

100 MB

Send WhatsApp Location Message  

If you would like to send a WhatsApp location message, 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. 

NOTE

When sending a WhatsApp location message, ‘longitude’ and ‘latitude’ are mandatory.

Location WhatsApp message request example: 

POST /omni/1/advanced HTTP/1.1 
Host: {base_url}
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

The contact message consists of an array of contact object. Each contact object consists of several objects, of which the name object is mandatory while others are optional.

Parameter

Type

Description

name

object

Full contact name.

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. It 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

Contact phone number.

waId

string

WhatsApp ID.

type

string

Type of a phone. It can be CELL, MAIN, IPHONE, HOME, WORK.

 

URLs

Parameter

Type

Contact

url

string

Contact URL.

type

string

Type of a URL. It 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: {base_url}
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."
	}
}

Incoming WhatsApp Messages

Incoming messages will be forwarded in real time to the end-point client provided during the setup. This way, 2-way communication will be established, and the enterprise is enabled to create a certain logic for processing incoming messages. 

NOTE

The endpoint needs to be provided by the client. The endpoint is the URL where your services can be accessed by the Infobip CPaaS platform. Infobip will complete the setup of the provided URL as part of the setup procedure on your behalf. The connection can be secured with additional authorization header between the Infobip CPaaS and the enterprises’ endpoint.

Text Incoming Message  

There are two ways of how incoming messages can be forwarded to the client's endpoint—they can be delivered with or without a contact name.

Example of an incoming message without a contact name:

{
  "results": [
    {
      "from": "385919998888",
      "to": "41793026731",
      "integrationType": "WHATSAPP",
      "receivedAt": "2019-07-19T11:21:27.861+0000",
      "messageId": "ABEGOFl3VCQoAhAqnlmSd2FKPOaraEaS0rPQ",
      "pairedMessageId": null,
      "callbackData": null,
      "message": {
        "type": "TEXT",
        "text": "Support hello"
      },
      "price": {
        "pricePerMessage": 0,
        "currency": "EUR"
      }
    }
  ],
  "messageCount": 1,
  "pendingMessageCount": 0
}

Example of the incoming message with the contact name:

{
  "results": [
    {
      "from": "385919998888",
      "to": "41793026731",
      "integrationType": "WHATSAPP",
      "receivedAt": "2019-07-19T11:23:26.998+0000",
      "messageId": "ABEGOFl3VCQoAhBalbc6rTQT6mgS29EmGZ7a",
      "pairedMessageId": null,
      "callbackData": null,
      "message": {
        "type": "TEXT",
        "text": "Support hello"
      },
      "contact": {
        "name": "Frank"
      },
      "price": {
        "pricePerMessage": 0,
        "currency": "EUR"
      }
    }
  ],
  "messageCount": 1,
  "pendingMessageCount": 0
}

You can choose between these two types and decide how you want to receive incoming messages. If you want to change from one type to another, you can contact our Support team at Suport@infobip.com.

NOTE

If, for example, you use the message with the contact name, this type will apply for the incoming messages with media as well (image, document, location, etc.).

Image Incoming Message  

{
    "results": [
        {
            "from": "385919998888",
            "to": "41793026731",
            "integrationType": "WHATSAPP",
            "receivedAt": "2018-09-10T11:27:17.980+0000",
            "messageId": "ABEGOFkWA5EBAgo6B82cNiWIAMKC",
            "pairedMessageId": null,
            "callbackData": null,
            "message": {
                "type": "IMAGE",
                "caption": "Image Caption",
                "url": "https://{base_url}/whatsapp/1/senders/447796344125/media/f1b96d31-9ab9-4513-808b-50ab37360fbe"
            },
            "price": {
                "pricePerMessage": 0.000000,
                "currency": "HRK"
            }
        }
    ],
    "messageCount": 1,
    "pendingMessageCount": 0
}

Document Incoming Message  

{
    "results": [
        {
            "from": "385919998888",
            "to": "41793026731",
            "integrationType": "WHATSAPP",
            "receivedAt": "2018-09-10T12:10:18.379+0000",
            "messageId": "ABEGOFkWA5EBAgo6B82cNiWIAMKC",
            "pairedMessageId": null,
            "callbackData": null,
            "message": {
                "type": "DOCUMENT",
                "caption": "Document caption",
                "url": "https://{base_url}/whatsapp/1/senders/447796344125/media/c256e11d-a7e9-4dbb-aa9c-2a6028ddf7e8"
            },
            "price": {
                "pricePerMessage": 0.000000,
                "currency": "HRK"
            }
        }
    ],
    "messageCount": 1,
    "pendingMessageCount": 0
}

Location Incoming Message  

{
    "results": [
        {
            "from": "385919998888",
            "to": "41793026731",
            "integrationType": "WHATSAPP",
            "receivedAt": "2020-05-27T09:43:43.798+0000",
            "messageId": "ABEGOFkWA5EBAgo6B82cNiWIAMKC",
            "pairedMessageId": null,
            "callbackData": null,
            "message": {
                "type": "LOCATION",
                "longitude": 15.945963382269058,
                "latitude": 45.7937660982851,
                "address": "Zadarska 80, Zagreb, Grad Zagreb 10000",
                "name": "Infobip ZG Office",
                "url": "http://infobip.com"
            },
            "contact": {
                "name": "Mark"
            },
            "price": {
                "pricePerMessage": 0,
                "currency": "EUR"
            }
        }
    ],
    "messageCount": 1,
    "pendingMessageCount": 1
}

Contact Incoming Message

{
  "results": [
    {
      "from": "385919998888",
      "to": "41793026731",
      "integrationType": "WHATSAPP",
      "receivedAt": "2019-09-24T10:07:04.070+0000",
      "messageId": "ABEGOFmJJRkFAhA7ud6mcWKmglIlIO6xibx9",
      "pairedMessageId": null,
      "callbackData": null,
      "message": {
        "contacts": [
          {
            "name": {
              "firstName": "Frank",
              "lastName": "Bipper",
              "formattedName": "Frank Bipper"
            },
            "org": {
              "company": "Infobip"
            },
            "phones": [
              {
                "phone": "+385 91 888 9999",
                "type": "Mobile",
                "waId": "385918889999"
              }
            ]
          }
        ],
        "price": {
          "pricePerMessage": 0,
          "currency": "EUR"
        },
        "messageCount": 1,
        "pendingMessageCount": 0
      }
    }
  ]
}

Video Incoming Message

{
  "results": [
    {
      "from": "385918889999",
      "to": "41793026731",
      "integrationType": "WHATSAPP",
      "receivedAt": "2019-09-24T12:21:06.486+0000",
      "messageId": "ABEGOFmJJRkFAhDvgHvPWYmCNKXZSQaqgH2A",
      "pairedMessageId": null,
      "callbackData": null,
      "message": {
        "caption": "Look at this!",
        "type": "VIDEO",
        "url": "https://{base_url}/whatsapp/1/senders/447860098731/media/42f076b9-1d1e-4d56-8c1e-02d0a402a1e3"
      },
      "price": {
        "pricePerMessage": 0,
        "currency": "EUR"
      }
    }
  ],
  "messageCount": 1,
  "pendingMessageCount": 0
}

Voice Incoming Message

{ 
    "results":[ 
       { 
          "from":"385919998888",
          "to":"41793026731",
          "integrationType":"WHATSAPP",
          "receivedAt":"2020-02-04T20:42:48.790+0000",
          "messageId":"ABEGVUGWh3gEAgo6XoxYzF6sEhdys",
          "pairedMessageId":null,
          "callbackData":null,
          "message":{ 
             "type":"VOICE",
             "url":"https://{base_url}/whatsapp/1/senders/554332947008/media/a852fb92-8506-4c3d-aab2-81bf436786e6"
          },
          "price":{ 
             "pricePerMessage":0.000000,
             "currency":"EUR"
          }
       }
    ],
    "messageCount":1,
    "pendingMessageCount":1113
 }

Audio Incoming Message

{ 
   "results":[ 
      { 
         "from":"385919998888",
         "to":"41793026731",
         "integrationType":"WHATSAPP",
         "receivedAt":"2020-02-06T14:18:29.797+0000",
         "messageId":"ABEGVUGWh3gEAgo-sLTvmQCS5kwjhsy",
         "pairedMessageId":null,
         "callbackData":null,
         "message":{ 
            "type":"AUDIO",
            "url":"https://{base_url/whatsapp/1/senders/551140038883/media/cb5608eb-aa38-454f-a045-899df74324e2"
         },
         "price":{ 
            "pricePerMessage":0.000000,
            "currency":"EUR"
         }
      }
   ],
   "messageCount":1,
   "pendingMessageCount":0
}

Button Incoming Message

{ 
   "results":[ 
      { 
         "from":"385919998888",
         "to":"447860064511",
         "integrationType":"WHATSAPP",
         "receivedAt":"2020-06-06T15:18:29.797+0000",
         "messageId":"ABEGVUGWh3gEAgo-sLTvmQCS5kwjhsy",
         "pairedMessageId":null,
         "callbackData":null,
         "message":{ 
            "type":"BUTTON",
            "text":"Yes",
            "context": { 
            "id": "b6a145a6-6f8c-4c7f-ac17-e13e128f1cb4", 
            "from": "447860064511" 
            },
            "payload":"POS-FEEDBACK"
         },
         "price":{ 
            "pricePerMessage":0.000000,
            "currency":"EUR"
         }
      }
   ],
   "messageCount":1,
   "pendingMessageCount":0
}

Incoming Message With Unsupported File

This is an example of incoming message with file that is not supported by WhatsApp.

{
  "results": [
    {
      "from": "385919998888",
      "to": "41793026731",
      "integrationType": "WHATSAPP",
      "receivedAt": "2020-02-17T17:49:56.091+0000",
      "messageId": "ABGHVRWYFQiSDwIKOgFDTFtK2dXIhg",
      "pairedMessageId": null,
      "callbackData": null,
      "message": {
        "type": "UNSUPPORTED"
      },
      "price": {
        "pricePerMessage": 0,
        "currency": "EUR"
      }
    }
  ],
  "messageCount": 1,
  "pendingMessageCount": 0
}

Receiving Incoming Media

Received media can be accessed for 30 days via two different methods:

  • The received URL can be opened in the browser while the client is logged in the Portal (note that it needs to be done in the same browser)
  • Using the received URL in API environment with GET method and setting the authorization header
GET /whatsapp/1/senders/{whatsapp sender}/media/{mediaId}
Host: {base_url} 
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 

Quoting Feature

Every incoming message from conversation that was quoted by end user will have context parameter. It consists of the id which shows messageId of message that was quoted and from which shows number that sent quoted message.  

{ 
  "results": [ 
    { 
      "from": "41793026727", 
      "to": "385919998888", 
      "integrationType": "WHATSAPP", 
      "receivedAt": "2020-02-03T15:37:58.003+0000", 
      "messageId": "ABEGOFl3VCQoAhDNeodbM8QvzQp_z99I9Lf6", 
      "pairedMessageId": null, 
      "callbackData": null, 
      "message": { 
        "context": { 
          "id": "b6a145a6-6f8c-4c7f-ac17-e13e128f1cb4", 
          "from": "385919998888" 
        }, 
        "text": "Hello support", 
        "type": "TEXT" 
      }, 
      "contact": { 
        "name": "Frank" 
      }, 
      "price": { 
        "pricePerMessage": 0, 
        "currency": "EUR" 
      } 
    } 
  ], 
  "messageCount": 1, 
  "pendingMessageCount": 0 
} 

Mark Incoming Messages as Read

This feature allows you to mark incoming messages as read. Note that this feature is not enabled by default. For more information, contact your Account Manager.

POST /whatsapp/1/senders/{whatsApp_sender}/message/{messageId}/read HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Deleting Media

Any media that is sent by end users is saved in cache for 30 days. To delete incoming and outgoing media from cache, use the request below:

DELETE /whatsapp/1/senders/{WhatsApp_Sender}/media HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
{
“url”:”{url_to_delete}”
}

Delivery and Seen Reports

Get Delivery Reports

Once you’ve successfully sent your messages, you can check the status of the sent messages using the OMNI reports method. 

The simplest way is to use the method without any query parameters. In that case, the response will contain all messages sent to a specific account. 

GET /omni/1/reports HTTP/1.1 
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Accept: application/json	

The response will contain all messages, rejected and delivered, as shown in the example below. 

HTTP/1.1 200 OK 
Content-Type: application/json 
 
{
    "results": [
        {
            "messageId": "1215f543ab19-345f-adbd-12ad31451ed25f35",
            "to": "41793026731",
            "sentAt": "2018-12-12T11:21:57.793+0000",
            "doneAt": "2018-12-12T11:21:58.771+0000",
            "messageCount": 1,
            "mccMnc": "null",
            "price": {
                "pricePerMessage": 0,
                "currency": "EUR"
            },
            "status": {
                "groupId": 3,
                "groupName": "DELIVERED",
                "id": 5,
                "name": "DELIVERED_TO_HANDSET",
                "description": "Message delivered to handset"
            },
            "error": {
                "groupId": 0,
                "groupName": "OK",
                "id": 0,
                "name": "NO_ERROR",
                "description": "No Error",
                "permanent": false
            },
            "channel": "WHATSAPP"
        }
    ]
}

For a complete list of all error codes and statuses, please refer to the following Response Codes and Error Codes article.

NOTE

You can also have delivery reports forwarded to your URL in real time. In that case, you should provide a URL to your Account Manager and they will set it up for you.

Real-Time Delivery Reports

Delivery reports that are forwarded to your URL in real time have a different format than the one that is retrieved using the OMNI reports method.

{
    "results": [{
        "bulkId": "",
        "price": {
            "pricePerMessage": 0.210000,
            "currency": "BRL"
        },
        "status": {
            "id": 5,
            "groupId": 3,
            "groupName": "DELIVERED",
            "name": "DELIVERED_TO_HANDSET",
            "description": "Message delivered to handset"
        },
        "error": {
            "id": 0,
            "name": "NO_ERROR",
            "description": "No Error",
            "groupId": 0,
            "groupName": "OK",
            "permanent": false
        },
        "messageId": "fb469d73-d362-463f-b30f-1e959b53badc",
        "doneAt": "2019-04-09T16:01:56.494-0300",
        "messageCount": 1,
        "sentAt": "2019-04-09T16:00:58.647-0300",
        "to": "41793026731",
        "channel": "WHATSAPP"
    }]
}

Receive WhatsApp Seen and Deleted Reports

Seen reports are always forwarded to the URL the client previously provides to Infobip.

Seen Report

{
    "results": [
        {
            "messageId": "1215f543ab19-345f-adbd-12ad31451ed25f35",
            "from": "385919998888",
            "to": "41793026731",
            "sentAt": "2018-12-12T11:21:57.793+0000",
            "seenAt": "2018-12-12T11:21:58.251+0000"
        }
    ]
}

Deleted Reports

Deleted reports are always forwarded to the URL the client previously provides to Infobip.

{
    "results": [
        {
            "messageId": "ABEGOFl3VCQoAhBos6wIvpBqxS2nTUbB4eBK",
            "from": "385919998888",
            "to": "41793026731",
            "sentAt": "2018-12-12T11:21:57.793+0000",
            "deletedAt": "2018-12-12T11:21:58.251+0000"
        }
    ]
}