Messages

WhatsApp Messages

Overview

Customers can send templated WhatsApp messages via Whispir's API. 

Templates must first be submitted for approval by WhatsApp in your WhatsApp Business Manager account before any template messages can be sent from Whispir. Please reach out to your Whispir account manager to help you get started.

  • JSON
  • XML

Send WhatsApp templated messages

{{codeStart}}

POST https://api.<region>.whispir.com/workspaces/:workspace_id/messages 

Headers:
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json
Authorisation: Basic/Bearer 

{
    "to": "61430933333",
    "subject": "message subject",
    "whatsapp": {
        "type": "icebreaker",
        "name": "igniteagain",
        "content": {
            "body": [
                {
                    "text": "hello"
                },
                {
                    "text": "world"
                }
            ]
        }
    }
}

{{codeEnd}}

Request Body Details

to

(required)

String

Ad-hoc recipients

  • Mobile phone: 61400400400

Defined Whispir recipients

  • Contact MRI:
    John_Smith.782749@Contact.whispir.com
  • User MRI:
    John_Smith@User.whispir.com
  • Distribution List MRI:
    Incidents.373947@List.whispir.com

subject

(required)

String

A description of the WhatsApp message to be sent

type

(required)
String

The type of WhatsApp message to be sent, e.g. "template".

Whispir currently only supports type "template". Other types such as "text", "image" etc may be supported in the future.
name

(required)
String

The name of the template to be sent (must be the same as how it appears in your WhatsApp Business Manager)
content

(required)
Array of objects

The content of your message contains any text and media that will be sent to the recipient. The contents can include a header, a body, and buttons.

The content object

header

Object

The header of your message can include one type of media content e.g. image, video, document and location.

For example:

"header": {
                "image": {
                    "link": "http://placekitten.com/200/300"
                }
            }

body

(required)

Array of objects

The contents of your WhatsApp message

buttonsArray of objects

The contents of your dynamic button.

If the button subtype is “url” you will need the following parameters:
“Index”, “sub_type”, “text”

If the button subtype is a “quick reply”, you will need the following parameters:
“Index”, “sub_type”, “payload

The header object

image

Object

Link to image location

video

Object

Link to video location

document

Object

Link to document location

location

Object

“Longitude”, "latitude", "name", and "address"

The button object

index

(required)

String

sub_type

(required)

String

The type of dynamic button i.e. "quick reply" or "url"

text
(required if sub_type = url)

String

the url destination when the button is clicked

payload
(required if sub_type = quick reply)

String

Name of the quick reply buttons configured within your WhatsApp Business Manager account.

WhatsApp API

WhatsApp API request payload examples with multimedia message support

1. Image example

{
    "to": "61430933333",
    "subject": "message subject",
    "whatsapp": {
        "type": "icebreaker",
        "name": "account_update_example_image_p",
        "content": {
            "header": {
                "image": {
                    "link": "http://placekitten.com/200/300"
                }
            },
            "body": [
                {
                    "text": "xxxxx"
                },
                {
                    "text": "yyyyy"
                },
                {
                    "text": "zzzzz"
                }
            ]
        }
    }
}

2. Video example

{
    "to": "61430933333",
    "subject": "message subject",
    "whatsapp": {
        "type": "icebreaker",
        "name": "account_update_example_video_p",
        "content": {
            "header": {
                "video": {
                    "link": "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4"
                }
            },
            "body": [
                {
                    "text": "11111"
                },
                {
                    "text": "22222"
                }
            ]
        }
    }
}

3. Text with fixed footer example

{
    "to": "61430933333",
    "subject": "message subject",
    "whatsapp": {
        "type": "icebreaker",
        "name": "standard_demo_01",
        "content": {
            "body": [
                {
                    "text": "11111"
                }
            ]
        }
    }
}

4. Document example

{
    "to": "61430933333",
    "subject": "message subject",
    "whatsapp": {
        "type": "icebreaker",
        "name": "account_update_example_doc_p",
        "content": {
            "header": {
                "document": {
                    "link": "https://s3-eu-west-1.amazonaws.com/hughhopkins.co.uk/sample_media/Sf+flight+itinerary.pdf"
                }
            },
            "body": [
                {
                    "text": "11111"
                },
                {
                    "text": "22222"
                }
            ]
        }
    }
}

5. Location example

{
    "to": "61430933333",
    "subject": "message subject",
    "whatsapp": {
        "type": "icebreaker",
        "name": "account_update_example_loc_p",
        "content": {
            "header": {
                "location": {
                    "longitude": -122.425332,
                    "latitude": 37.758056,
                    "name": "Facebook HQ",
                    "address": "1 Hacker Way, Menlo Park, CA 94025"
                }
            },
            "body": [
                {
                    "text": "11111"
                },
                {
                    "text": "22222"
                }
            ]
        }
    }
}

6. Image & quick reply example

{
    "to": "61430933333",
    "subject": "message subject",
    "whatsapp": {
        "type": "icebreaker",
        "name": "aue_image_quick_reply",
        "content": {
            "header": {
                "image": {
                    "link": "http://placekitten.com/200/300"
                }
            },
            "body": [
                {
                    "text": "11111"
                },
                {
                    "text": "22222"
                },
                {
                    "text": "33333"
                }
            ],
            "button": [
                {
                    "index": "0",
                    "sub_type": "quick_reply",
                    "payload": "Yes-Button-Payload"
                },
                {
                    "index": "1",
                    "sub_type": "quick_reply",
                    "payload": "No-Button-Payload"
                }
            ]
        }
    }
}

7. Link button (static url) example

 {
    "to": "61430933333",
    "subject": "message subject",
    "whatsapp": {
        "type": "icebreaker",
        "name": "aue_location_cta_static",
        "content": {
            "header": {
                "location": {
                    "longitude": -122.425332,
                    "latitude": 37.758056,
                    "name": "Facebook HQ",
                    "address": "1 Hacker Way, Menlo Park, CA 94025"
                }
            },
            "body": [
                {
                    "text": "11111"
                },
                {
                    "text": "22222"
                }
            ]
        }
    }
}

8. Link button (static url + call phone number) example

{
    "to": "61430933333",
    "subject": "message subject",
    "whatsapp": {
        "type": "icebreaker",
        "name": "hsbc_alert",
        "content": {
            "body": [
                {
                    "text": "111"
                },
                {
                    "text": "222"
                },
                {
                    "text": "333"
                },
                {
                    "text": "444"
                },
                {
                    "text": "555"
                }
            ]
        }
    }
}

9. Link button (dynamic) example

{
    "to": "61430933333",
    "subject": "message subject",
    "whatsapp": {
        "type": "icebreaker",
        "name": "new_media_message_rules",
        "content": {
            "header": {
                "image": {
                    "link": "http://placekitten.com/200/300"
                }
            },
            "body": [
                {
                    "text": "11111"
                }
            ],
            "buttons": [
                {
                    "index": "0",
                    "sub_type": "url",
                    "text": "search?q=Whisprr"
                }
            ]
        }
    }
}

How to query sent message status using WhatsApp's API /status endpoint

10. WhatsApp API: GET message status

GET: https://whatsapp.ap1.whispir.com/status
Headers: 
Content-Type: application/json
Authorisation: Bearer

11. WhatsApp API: Query messages by Id

GET: https://whatsapp.ap1.whispir.com/status/89886399
Headers: 
Content-Type: application/json
Authorisation: Bearer

12. WhatsApp API: Query messages by status

(SENT/SUBMITTED/DELIVERED/READ/FAILED/REJECTED/UNDELIVERABLE)

GET: https://whatsapp.ap1.whispir.com/status?status=SENT
Headers: 
Content-Type: application/json
Authorisation: Bearer

13. WhatsApp API: Query messages by sender number (from_phone_number)

GET: https://whatsapp.ap1.whispir.com/status?sender=61430430
Headers: 
Content-Type: application/json
Authorisation: Bearer

14. WhatsApp API: Query messages by recipient number (to_phone_number)

GET: https://whatsapp.ap1.whispir.com/status?recipient=61430430
Headers: 
Content-Type: application/json
Authorisation: Bearer

15. WhatsApp API: Query messages by a time range (start date/time - end date/time)

GET: https://whatsapp.ap1.whispir.com/status?startTime=2020-12-03T02:32:42Z&endTime=2030-03-11T02:32:42Z
Headers: 
Content-Type: application/json
Authorisation: Bearer

How to create & edit templates using WhatsApp's API /templates endpoint

16. Retrieve all templates by using the /templates endpoint with GET

Sample request

GET http://whatsapp.[region].whispir.com/templates
Headers: 
Content-Type: application/json
Authorisation: Bearer

Sample response

[
    {
        "id": "15",
        "name": "_test_1234_template_1",
        "whatsappId": "req:body:whatsappId",
        "type": "TEXT_TEMPLATE",
        "description": "This is a test template",
        "content": "test template",
        "parameter": "test parameters",
        "language": "{\"en\"}",
        "ownerCompanyId": "64",
        "created": "2020-07-20T02:58:09.671Z",
        "modified": "2020-07-20T02:58:09.671Z"
    },
    {
        "id": "16",
        "name": "_test_1234_template_2",
        "whatsappId": "req:body:whatsappId",
        "type": "TEXT_TEMPLATE",
        "description": "This is a test template",
        "content": "test template",
        "parameter": "test parameters",
        "language": "{\"en\"}",
        "ownerCompanyId": "64",
        "created": "2020-07-20T02:58:09.698Z",
        "modified": "2020-07-20T02:58:09.698Z"
    }
]

17. Create new template by using /templates endpoint with POST

Sample request

POST http://whatsapp.[region].whispir.com/templates
Headers: 
Content-Type: application/json
Authorisation: Bearer

Payload

{
  "name": "igniteagain",
  "whatsappId": "5d63f94c_f696_bcbb_9da6_d6853d575f90:igniteagain",
  "content": "Hello, your account has been updated. Please visit {{1}} or {{2}} for more information", 
  "description": "This is a test template",
  "parameter": "{\"parameter_count\":0,\"parameter_data\":[]}"
}

** required fields: "name", "whatsappId","content"
** "name": must be low case, number and underscore
** "name": maximum 30 characters

Sample response

{
    "id": "17",
    "name": "igniteagain",
    "whatsappId": "5d63f94c_f696_bcbb_9da6_d6853d575f90:igniteagain",
    "type": "TEXT_TEMPLATE",
    "description": "This is a test template",
    "content": "Hello, your account has been updated. Please visit {{1}} or {{2}} for more information",
    "parameter": "{\"parameter_count\":0,\"parameter_data\":[]}",
    "language": "{\"en\"}",
    "ownerCompanyId": "64",
    "created": "2020-07-20T05:31:29.537Z",
    "modified": "2020-07-20T05:31:29.537Z"
}

18. Delete template by using /templates/<templateName> endpoint with DELETE

Sample request

DELETE http://whatsapp.[region].whispir.com/templates/testName

Sample response

{
    "message": "Template with name testName deleted."
}

19. Retrieve a single template's details by using /templates/<templateID> endpoint with GET

Sample request

GET http://whatsapp.[region].whispir.com/templates/templateId
Headers: 
Content-Type: application/json
Authorisation: Bearer

Sample response

{
    "id": "17",
    "name": "igniteagain",
    "whatsappId": "5d63f94c_f696_bcbb_9da6_d6853d575f90:igniteagain",
    "type": "TEXT_TEMPLATE",
    "description": "This is a test template",
    "content": "Hello, your account has been updated. Please visit {{1}} or {{2}} for more information",
    "parameter": "{\"parameter_count\":0,\"parameter_data\":[]}",
    "language": "{\"en\"}",
    "ownerCompanyId": "64",
    "created": "2020-07-20T05:31:29.537Z",
    "modified": "2020-07-20T05:31:29.537Z"
}

20. Edit a single template's details by using /templates/<templateID> endpoint with GET

Sample request

{
  "name": "otp_1",
  "whatsappId": "5d63f94c_f696_bcbb_9da6_d6853d575f90:igniteagain",
  "content": "Hello, your account has been updated. Please visit {{1}} or {{2}} for more information", 
  "description": "This is a test template",
  "parameter": "{\"parameter_count\":0,\"parameter_data\":[]}"
}

Sample response

{
    "id": "17",
    "name": "igniteagain",
    "whatsappId": "5d63f94c_f696_bcbb_9da6_d6853d575f90:igniteagain",
    "type": "TEXT_TEMPLATE",
    "description": "This is a test template",
    "content": "Hello, your account has been updated. Please visit {{1}} or {{2}} for more information",
    "parameter": "{\"parameter_count\":0,\"parameter_data\":[]}",
    "language": "{\"en\"}",
    "ownerCompanyId": "64",
    "created": "2020-07-20T05:31:29.537Z",
    "modified": "2020-07-20T05:31:29.537Z"
}

How to get reports using WhatsApp's API /reports endpoint

21. View message delivery reports by using the /reports endpoint with GET

Sample request

GET http://whatsapp.[region].whispir.com/reports
Headers: 
Content-Type: application/json
Authorisation: Bearer

Following query parameters are supported:

  • to - Recipient contact number
  • from - Sender contact number
  • userId - Sender Id
  • startDate - Messages sent from this date
  • endDate - Messages sent until this date

Sample response:

  • Can be downloaded in CSV format. 
  • Output columns: Message ID, Workspace, User ID, Time, Type, Template, From, To, Status