diff --git a/docs/Message types/WhatsApp-messages.md b/docs/Message types/WhatsApp-messages.md new file mode 100644 index 0000000..0c03f1a --- /dev/null +++ b/docs/Message types/WhatsApp-messages.md @@ -0,0 +1,269 @@ +--- +internal: true +--- + +# 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. + +## How to query sent message status using WhatsApp's API /status endpoint + +### WhatsApp API: GET message status + +```json +GET: https://whatsapp.ap1.whispir.com/status +Headers: +Content-Type: application/json +Authorisation: Bearer +``` + +### WhatsApp API: Query messages by Id + +```json +GET: https://whatsapp.ap1.whispir.com/status/89886399 +Headers: +Content-Type: application/json +Authorisation: Bearer +``` + +### WhatsApp API: Query messages by status + +(SENT/SUBMITTED/DELIVERED/READ/FAILED/REJECTED/UNDELIVERABLE) + +```json +GET: https://whatsapp.ap1.whispir.com/status?status=SENT +Headers: +Content-Type: application/json +Authorisation: Bearer +``` + +### hatsApp API: Query messages by sender number (from_phone_number) + +```json +GET: https://whatsapp.ap1.whispir.com/status?sender=61430430 +Headers: +Content-Type: application/json +Authorisation: Bearer +``` + +### WhatsApp API: Query messages by recipient number (to_phone_number) + +```json +GET: https://whatsapp.ap1.whispir.com/status?recipient=61430430 +Headers: +Content-Type: application/json +Authorisation: Bearer +``` + +### WhatsApp API: Query messages by a time range (start date/time - end date/time) + +```json +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 + +### Retrieve all templates by using the /templates endpoint with GET + +#### Sample request: + +```json +GET http://whatsapp.[region].whispir.com/templates +Headers: +Content-Type: application/json +Authorisation: Bearer +``` + +#### Sample response: + +```json +[ + { + "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" + } +] +``` + +### Create new template by using /templates endpoint with POST + +#### Sample request + +```json +POST http://whatsapp.[region].whispir.com/templates +Headers: +Content-Type: application/json +Authorisation: Bearer +``` + +#### Payload + +```json +{ + "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 + +```json +{ + "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" +} +``` + +### Delete template by using /templates/ endpoint with DELETE + +#### Sample request + +```json +DELETE http://whatsapp.[region].whispir.com/templates/testName +``` + +#### Sample response + +```json +{ + "message": "Template with name testName deleted." +} +``` + +### Retrieve a single template's details by using /templates/ endpoint with GET + +#### Sample request + +```json +GET http://whatsapp.[region].whispir.com/templates/templateId +Headers: +Content-Type: application/json +Authorisation: Bearer +``` + +#### Sample response + +```json +{ + "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" +} +``` + +### Edit a single template's details by using /templates/ endpoint with GET + +#### Sample request + +```json +{ + "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 + +```json +{ + "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 + +### View message delivery reports by using the /reports endpoint with GET + +#### Sample request + +```json +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 + +| Column A | Column B | +| -------- | -------- | +| A1 | B1 | +| A2 | B2 | +| A3 | B3 | diff --git a/openapi.yaml b/openapi.yaml index dc15f2e..f4a8571 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -84,7 +84,8 @@ paths: - **SMS** - up to 1600 characters per message, premium routes, delivery receipts - **Email** - free email messaging with HTML and Plain Text support - **Voice** - high quality outbound voice calls delivered to mobiles and landlines within seconds - - **Rich Messages** - personalised, targeted rich messaging to drive conversations + - **Rich Messages** - personalised, targeted rich messaging to drive conversations + - **WhatsApp** - customised WhatsApp messages featuring mutliple content types (__presently only available in AP1 region__) - **Twitter** - support for instant publishing to multiple twitter accounts - **Facebook** - simplify the process of publishing to multiple facebook accounts instantaneously - **RSS** - easily generate RSS feeds for consumption by other services @@ -371,9 +372,7 @@ paths: A message is scheduled according to the timezone set in the Whispir account of the user who initiates the message request. This setting can be found in the Whispir Portal under "Settings"->"User Manager"->"View/Edit". Whispir DOES NOT honor the timezone where the sender or the message recipient are currently located in For example if the user’s time zone is set to UTC in their Whispir profile then messages are scheduled to be sent as per UTC, even if the user triggers the message while sitting in Singapore (+8). So please ensure that any scheduled communication is sent at the appropriate/preferred time Also, changing the user's timezone setting after the message is triggered DOES NOT change the original scheduled time. - #### Sending messages at a later date - ```JSON POST https://api..whispir.com/workspaces/{workspaceId}/messages @@ -462,6 +461,15 @@ paths: application/vnd.whispir.message-v1+json: schema: $ref: '#/components/schemas/message' + application/vnd.whispir.bulkmessage-v1+json: + schema: + $ref: '#/components/schemas/message' + application/vnd.whispir.message-v1+xml: + schema: + $ref: '#/components/schemas/message' + application/vnd.whispir.bulkmessage-v1+xml: + schema: + $ref: '#/components/schemas/message' examples: SMS: value: @@ -5617,6 +5625,8 @@ components: $ref: '#/components/schemas/web' social: $ref: '#/components/schemas/social' + whatsapp: + $ref: '#/components/schemas/whatsapp' type: type: string enum: @@ -7573,6 +7583,149 @@ components: xml: name: fieldMapping title: Field Mapping + whatsapp: + description: A structured WhatsApp channel payload. + type: object + x-examples: + Example: + type: icebreaker + name: igniteagain + content: + body: + - text: hello + - text: world + title: WhatsApp + properties: + type: + type: string + description: The type of WhatsApp message to be sent. + enum: + - template + name: + type: string + description: The name of the template to be sent (must be the same as how it appears in your WhatsApp Business Manager). + content: + type: object + description: The WhatsApp message payload. + required: + - body + properties: + header: + $ref: '#/components/schemas/whatsapp_header' + body: + type: array + description: Message body is an array of text objects. + items: + type: object + minProperties: 1 + properties: + text: + type: string + description: Text objects in the array are inserted into variable fields in the WhatsApp template. + required: + - text + buttons: + type: array + description: An array of whatsapp_button objects. Each object represents one button in the WhatsApp message. + items: + $ref: '#/components/schemas/whatsapp_button' + required: + - type + - name + - content + whatsapp_header: + title: whatsapp_header + type: object + x-examples: + image-example: + image: + link: 'http://placekitten.com/200/300' + video-example: + video: + link: 'https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4' + document-example: + document: + link: 'https://s3-eu-west-1.amazonaws.com/hughhopkins.co.uk/sample_media/Sf+flight+itinerary.pdf' + location-example: + location: + longitude: -122.425332 + latitude: 37.758056 + name: Facebook HQ + address: '1 Hacker Way, Menlo Park, CA 94025' + description: Optional header for a Whatsapp message. + properties: + image: + type: string + description: Link to image location. + format: uri + example: 'http://placekitten.com/200/300' + video: + type: string + description: Link to video location. + format: uri + example: 'https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4' + document: + type: string + description: Link to document location. + format: uri + example: 'https://s3-eu-west-1.amazonaws.com/hughhopkins.co.uk/sample_media/Sf+flight+itinerary.pdf' + location: + type: object + description: A location for the header. + properties: + longitude: + example: -122.425332 + description: Location longitude. + type: number + latitude: + type: number + example: 37.758056 + description: Location latitude. + name: + type: string + example: Facebook HQ + description: Location name. + address: + type: string + example: '1 Hacker Way, Menlo Park, CA 94025' + description: Location street address. + required: + - longitude + - latitude + - name + - address + whatsapp_button: + title: whatsapp_button + type: object + description: Button object for a WhatsApp message. + x-examples: + quick-reply-example: + index: '0' + sub_type: quick_reply + payload: Yes-Button-Payload + url-example: + index: '0' + sub_type: url + text: 'https://www.google.com/search?q=Whispir' + properties: + index: + type: string + description: The index of the object in the array. + sub_type: + type: string + description: The type of dynamic button. + enum: + - quick reply + - url + text: + type: string + description: The url destination when the button is clicked. Required if sub_type = url. + payload: + type: string + description: 'Name of the quick reply buttons configured within your WhatsApp Business Manager account. Required if sub_type = quick reply. ' + required: + - index + - sub_type attachment: type: object description: |-