From c8c5c3b797e25544158eea88c7db45d1599ec582 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Thu, 3 Mar 2022 13:06:52 +1100 Subject: [PATCH 01/26] Modified openapi.yaml --- openapi.yaml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 5dcb710..4690c21 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4119,6 +4119,21 @@ components: xml: name: fieldMapping title: Field Mapping + whatsapp: + title: whatsapp + type: object + properties: + to: + type: string + subject: + type: string + type: + type: string + name: + type: string + content: + type: array + items: {} parameters: x-api-key: name: x-api-key From b75043b4c7d7e39e9f94bb68fefe7f13824151d6 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Thu, 3 Mar 2022 13:55:24 +1100 Subject: [PATCH 02/26] Modified openapi.yaml --- openapi.yaml | 134 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 127 insertions(+), 7 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 4690c21..ef49f19 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 of multiple message types - **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 @@ -3344,6 +3345,8 @@ components: $ref: '#/components/schemas/web' social: $ref: '#/components/schemas/social' + whatsapp: + $ref: '#/components/schemas/whatsapp' type: type: string enum: @@ -4120,20 +4123,137 @@ components: name: fieldMapping title: Field Mapping whatsapp: - title: whatsapp + description: This object represents a WhatsApp message to be used with the POST /messages method. type: object + x-examples: + hello-world: + to: '61430933333' + subject: message subject + whatsapp: + type: icebreaker + name: igniteagain + content: + body: + - text: hello + - text: world properties: to: type: string + minLength: 1 + description: Message recipient. Can be ad hoc (e.g. phone number) or a defined Whispir recipient (e.g. Contact MRI "John_Smith.782749@Contact.whispir.com". subject: type: string - type: + minLength: 1 + description: A description of the WhatsApp message to be sent. + whatsapp: + type: object + description: The WhatsApp message payload. + required: + - type + - name + - content + properties: + type: + type: string + minLength: 1 + description: Type of WhatsApp message. + name: + type: string + minLength: 1 + description: Intenal name for message e.g. "aue_image_quick_reply". + content: + type: object + description: WhatsApp message content. + required: + - body + properties: + header: + $ref: '#/components/schemas/whatsapp_header' + body: + type: array + description: An array of WhatsApp body objects. Each object represents one line of text in the sent message. Minumum 1 required. + items: + $ref: '#/components/schemas/whatsapp_body' + buttons: + type: array + description: An array of WhatsApp button objects. One object per button. Optional. + items: + $ref: '#/components/schemas/whatsapp_button' + required: + - to + - subject + - whatsapp + 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 object for a Whatsapp message. + properties: + image: type: string - name: + description: Link to image location. + video: type: string - content: - type: array - items: {} + description: Link to video location. + document: + type: string + description: Link to document location. + location: + type: string + description: '“Longitude”, "latitude", "name", and "address".' + whatsapp_button: + title: whatsapp_button + type: object + description: Optional button object for a WhatsApp message. + properties: + index: + type: string + sub_type: + type: string + description: The type of dynamic button i.e. "quick reply" or "url". + text: + type: string + description: Required if sub_type = url. The url destination when the button is clicked. + payload: + type: string + description: Required if sub_type = quick reply. Name of the quick reply buttons configured within your WhatsApp Business Manager account. + required: + - index + - sub_type + 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' + whatsapp_body: + title: whatsapp_body + type: object + description: Textual body of a WhatsApp message. + properties: + text: + type: string + description: A line of text in a WhatsApp message. + required: + - text parameters: x-api-key: name: x-api-key From 0f76472133d34f4b642fb69cdc3d1895ae25c856 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Thu, 3 Mar 2022 14:16:30 +1100 Subject: [PATCH 03/26] Modified openapi.yaml --- openapi.yaml | 72 +++++++++++++++++++--------------------------------- 1 file changed, 26 insertions(+), 46 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index ef49f19..fc3978d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4123,66 +4123,46 @@ components: name: fieldMapping title: Field Mapping whatsapp: - description: This object represents a WhatsApp message to be used with the POST /messages method. + description: This object is a WhatsApp message payload to be used with the POST /messages method. type: object x-examples: hello-world: - to: '61430933333' - subject: message subject - whatsapp: - type: icebreaker - name: igniteagain - content: - body: - - text: hello - - text: world + type: icebreaker + name: igniteagain + content: + body: + - text: hello + - text: world properties: - to: + type: type: string minLength: 1 - description: Message recipient. Can be ad hoc (e.g. phone number) or a defined Whispir recipient (e.g. Contact MRI "John_Smith.782749@Contact.whispir.com". - subject: + description: Type of WhatsApp message. + name: type: string minLength: 1 - description: A description of the WhatsApp message to be sent. - whatsapp: + description: Internal name for message e.g. "aue_image_quick_reply". + content: type: object description: The WhatsApp message payload. required: - - type - - name - - content + - body properties: - type: - type: string - minLength: 1 - description: Type of WhatsApp message. - name: + header: + $ref: '#/components/schemas/whatsapp_header' + body: + type: + - string + - array + description: An array of whatsapp_body objects. + items: + $ref: '#/components/schemas/whatsapp_body' + buttons: type: string - minLength: 1 - description: Intenal name for message e.g. "aue_image_quick_reply". - content: - type: object - description: WhatsApp message content. - required: - - body - properties: - header: - $ref: '#/components/schemas/whatsapp_header' - body: - type: array - description: An array of WhatsApp body objects. Each object represents one line of text in the sent message. Minumum 1 required. - items: - $ref: '#/components/schemas/whatsapp_body' - buttons: - type: array - description: An array of WhatsApp button objects. One object per button. Optional. - items: - $ref: '#/components/schemas/whatsapp_button' required: - - to - - subject - - whatsapp + - type + - name + - content whatsapp_header: title: whatsapp_header type: object From 56128cf1eccca9ddb9914fb7ccc100b4b3b29aa7 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Thu, 3 Mar 2022 15:29:54 +1100 Subject: [PATCH 04/26] Modified openapi.yaml --- openapi.yaml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index fc3978d..0822cd4 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -174,7 +174,7 @@ paths: application/vnd.whispir.bulkmessage-v1+xml: schema: $ref: '#/components/schemas/message' - description: 'Message object needed to create message. At least one of the Body fields must be populated [SMS, email, voice or web].' + description: 'Message object needed to create message. At least one of the Body fields must be populated [SMS, email, voice, web or whatsapp].' required: true responses: '202': @@ -4154,11 +4154,14 @@ components: type: - string - array - description: An array of whatsapp_body objects. + description: An array of whatsapp_body objects. Each object represents a line of text in the WhatsApp message. Minimum 1 required. items: $ref: '#/components/schemas/whatsapp_body' buttons: - type: string + 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 From 50adb8d8bbe0c2688b7d7cd175dc01622c989980 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Thu, 3 Mar 2022 16:35:41 +1100 Subject: [PATCH 05/26] Modified openapi.yaml --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 0822cd4..2c05482 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4137,7 +4137,7 @@ components: type: type: string minLength: 1 - description: Type of WhatsApp message. + description: 'The type of WhatsApp message to be sent, e.g. "template".' name: type: string minLength: 1 From 1199746fe44ac8eddad258cd9ebf8cbdf93819a0 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Thu, 3 Mar 2022 16:39:48 +1100 Subject: [PATCH 06/26] Modified openapi.yaml --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 2c05482..4f35e10 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -85,7 +85,7 @@ paths: - **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 - - **WhatsApp** - customised WhatsApp messages of multiple message types + - **WhatsApp** - customised WhatsApp messages featuring mutliple content types - **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 From 55692095cac3d32d812d9593fa62dd95f0b1e941 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Thu, 3 Mar 2022 16:40:55 +1100 Subject: [PATCH 07/26] Modified openapi.yaml --- openapi.yaml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 4f35e10..d83c186 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4151,9 +4151,7 @@ components: header: $ref: '#/components/schemas/whatsapp_header' body: - type: - - string - - array + type: array description: An array of whatsapp_body objects. Each object represents a line of text in the WhatsApp message. Minimum 1 required. items: $ref: '#/components/schemas/whatsapp_body' From fe65be847c6f5da4cb697559617a565e0d2b966d Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Fri, 4 Mar 2022 10:30:57 +1100 Subject: [PATCH 08/26] Modified openapi.yaml --- openapi.yaml | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index d83c186..101d22d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4152,9 +4152,9 @@ components: $ref: '#/components/schemas/whatsapp_header' body: type: array - description: An array of whatsapp_body objects. Each object represents a line of text in the WhatsApp message. Minimum 1 required. + description: 'Message body is an array of strings. Each string should be labeled ''text''. Each string will appear as one line of text in WhatsApp messasge (see example). Minimum 1 string required. ' items: - $ref: '#/components/schemas/whatsapp_body' + type: string buttons: type: array description: An array of whatsapp_button objects. Each object represents one button in the WhatsApp message. @@ -4225,16 +4225,6 @@ components: index: '0' sub_type: url text: 'https://www.google.com/search?q=Whispir' - whatsapp_body: - title: whatsapp_body - type: object - description: Textual body of a WhatsApp message. - properties: - text: - type: string - description: A line of text in a WhatsApp message. - required: - - text parameters: x-api-key: name: x-api-key From a0f60889dcbc9a290ae7aae7088276ea3b8be69f Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Fri, 4 Mar 2022 10:48:52 +1100 Subject: [PATCH 09/26] Modified 2 files --- docs/Message types/WhatsApp-messages.md | 20 ++++++++++++++++++++ toc.json | 9 +++++++++ 2 files changed, 29 insertions(+) create mode 100644 docs/Message types/WhatsApp-messages.md diff --git a/docs/Message types/WhatsApp-messages.md b/docs/Message types/WhatsApp-messages.md new file mode 100644 index 0000000..5e6e428 --- /dev/null +++ b/docs/Message types/WhatsApp-messages.md @@ -0,0 +1,20 @@ +# 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. + +See [here](openapi.yaml/components/schemas/whatsapp) + +```json json_schema +{ + "type": "object", + "properties": { + "id": { + "type": "string" + } + } +} +``` \ No newline at end of file diff --git a/toc.json b/toc.json index d2a606a..c7ecb0f 100644 --- a/toc.json +++ b/toc.json @@ -43,6 +43,15 @@ "type": "item", "title": "Whispir API Postman Collection", "uri": "docs/Getting started/Whispir-API-Postman-Collection.md" + }, + { + "type": "divider", + "title": "Message types" + }, + { + "type": "item", + "title": "WhatsApp messages", + "uri": "docs/Message types/WhatsApp-messages.md" }, { "type": "divider", From 131c02d8b04bbed1b905158886d21fd9ba57078c Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Fri, 4 Mar 2022 11:18:03 +1100 Subject: [PATCH 10/26] Modified 2 files --- docs/Message types/WhatsApp-messages.md | 93 +++++++++++++++++++++++-- openapi.yaml | 2 +- 2 files changed, 89 insertions(+), 6 deletions(-) diff --git a/docs/Message types/WhatsApp-messages.md b/docs/Message types/WhatsApp-messages.md index 5e6e428..a623fe6 100644 --- a/docs/Message types/WhatsApp-messages.md +++ b/docs/Message types/WhatsApp-messages.md @@ -6,15 +6,98 @@ 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. -See [here](openapi.yaml/components/schemas/whatsapp) +### WhatsApp structured data object + +This object can sent via a `POST` call to the `/messages` endpoint. + +The JSON scheme is as follows: ```json json_schema { - "type": "object", - "properties": { - "id": { - "type": "string" + "object": "whatsapp": { + "description": "This object is a WhatsApp message payload to be used with the POST /messages method.", + "type": "object", + "properties": { + "type": { + "type": "string", + "minLength": 1, + "description": "The type of WhatsApp message to be sent, e.g. \"template\"." + }, + "name": { + "type": "string", + "minLength": 1, + "description": "Internal name for message e.g. \"aue_image_quick_reply\"." + }, + "content": { + "type": "object", + "description": "The WhatsApp message payload.", + "required": [ + "body" + ], + "properties": { + "header": { + "type": "object", + "description": "Optional header for a Whatsapp message.", + "properties": { + "image": { + "type": "string", + "description": "Link to image location." + }, + "video": { + "type": "string", + "description": "Link to video location." + }, + "document": { + "type": "string", + "description": "Link to document location." + }, + "location": { + "type": "string", + "description": "“Longitude”, \"latitude\", \"name\", and \"address\"." + } } + }, + + "body": { + "type": "array", + "description": "Message body is an array of strings. Each string should be labeled 'text'. Each string will appear as one line of text in WhatsApp messasge. Minimum 1 string required. ", + "items": { + "type": "string" + } + }, + "buttons": { + "type": "object", + "description": "Optional button object for a WhatsApp message. Multiple buttons can be added when placed in an array.", + "properties": { + "index": { + "type": "string" + }, + "sub_type": { + "type": "string", + "description": "The type of dynamic button i.e. \"quick reply\" or \"url\"." + }, + "text": { + "type": "string", + "description": "Required if sub_type = url. The url destination when the button is clicked." + }, + "payload": { + "type": "string", + "description": "Required if sub_type = quick reply. Name of the quick reply buttons configured within your WhatsApp Business Manager account." + } + }, + "required": [ + "index", + "sub_type" + ] + } + } + } + }, + "required": [ + "type", + "name", + "content" + ] } } ``` \ No newline at end of file diff --git a/openapi.yaml b/openapi.yaml index 101d22d..688d973 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4183,7 +4183,7 @@ components: latitude: 37.758056 name: Facebook HQ address: '1 Hacker Way, Menlo Park, CA 94025' - description: Optional object for a Whatsapp message. + description: Optional header for a Whatsapp message. properties: image: type: string From 5203c33f535dbb7c4bca634856ab416e7eeaeb31 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Fri, 4 Mar 2022 14:14:00 +1100 Subject: [PATCH 11/26] Modified docs/Message types/WhatsApp-messages.md --- docs/Message types/WhatsApp-messages.md | 219 +++++++++++++++++++++++- 1 file changed, 217 insertions(+), 2 deletions(-) diff --git a/docs/Message types/WhatsApp-messages.md b/docs/Message types/WhatsApp-messages.md index a623fe6..49b40ad 100644 --- a/docs/Message types/WhatsApp-messages.md +++ b/docs/Message types/WhatsApp-messages.md @@ -10,7 +10,7 @@ Templates must first be submitted for approval by WhatsApp in your WhatsApp Busi This object can sent via a `POST` call to the `/messages` endpoint. -The JSON scheme is as follows: +The JSON schema for the 'whatsapp' object is s as follows: ```json json_schema { @@ -100,4 +100,219 @@ The JSON scheme is as follows: ] } } -``` \ No newline at end of file +``` + +## 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 \ No newline at end of file From a64ec1dbf82b9874024fad1b867e8ef9c7b70233 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Fri, 4 Mar 2022 15:24:51 +1100 Subject: [PATCH 12/26] Modified 2 files --- docs/Message types/WhatsApp-messages.md | 10 ++- openapi.yaml | 83 ++++++++++++++++++++++++- 2 files changed, 91 insertions(+), 2 deletions(-) diff --git a/docs/Message types/WhatsApp-messages.md b/docs/Message types/WhatsApp-messages.md index 49b40ad..0092705 100644 --- a/docs/Message types/WhatsApp-messages.md +++ b/docs/Message types/WhatsApp-messages.md @@ -315,4 +315,12 @@ Following query parameters are supported: - 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 \ No newline at end of file +- Output columns: Message ID, Workspace, User ID, Time, Type, Template, From, To, Status + + + +Column A | Column B | +---------|---------- + A1 | B1 | + A2 | B2 | + A3 | B3 | \ No newline at end of file diff --git a/openapi.yaml b/openapi.yaml index 688d973..c8097ca 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -78,7 +78,7 @@ paths: tags: - Messages summary: Send a message - description: | + description: |- Communications are the core of what the Whispir Platform API offers as a service to customers. Whispir has the ability to send communications across 7 different channels in a single API request: - **SMS** - up to 1600 characters per message, premium routes, delivery receipts @@ -135,6 +135,87 @@ paths: Now we have the templateId(for content) with the resourceID (for recipients). Using these two key pieces of information, developers can submit an API request to kick off the Dynamic Messaging process. The smsMappingField should be mapped to the column or key that holds the number to which the SMS has to sent to; and the emailMappingField to the email to which the message has to be sent to. + + * * * + ## Native message variables + When sending messages using the Whispir API you can automatically customise your communications including recipients information as part of the message. This is facilitated by the Whispir's native message variables [or native tags] that will be resolved against the recipients MRIs. + + > **IMPORTANT**: the following tags can be included in any SMS, email or voice message. They are NOT meant to be used in rich messages. In this case recipient-specific fields can be populated using the Whispir JavaScript API. + + Contact tag| Description| + ---------|---------- + @@first_name@@ | Recipient’s first name.
For example, John. + @@last_name@@ | Recipient’s last name.
For example, Smith. + @@recipient_email@@ | Recipient’s primary email address.
For example, jsmith@email.com + @@recipient_sms@@ | Recipient’s primary mobile phone number.

For example, 61400400400. + @@recipient_voice@@ | Recipient’s primary phone number for voice calls.

For example, 61400400400. + @@pin@@ | Whispir message retrieval service call back PIN (only populated when voice is used).

For example, 1234. + @@recipient_role@@ | Resolves to the recipient’s ‘Role’ field.

For example, Manager. + @@recipient_additionalrole@@ | Resolves to the recipient’s ‘Additional Role’ field.

For example, Team Leader. + @@team_name1@@ | Resolves to the recipient’s ‘Team Name’ field.

For example, Red Team. + @@messagelabel@@| Resolves to the label field of the sent message.

For example, Incident #1234. + @@messagecategories@@ | Resolves to the list of categories used in the message, separated with commas.

For example, Product Update. + + ``` JSON + # To call from a User-defined workspace + POST https://api..whispir.com/workspaces/:workspace_id/messages + # To call from the default workspace + POST https://api..whispir.com/messages + + Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk + x-api-key: your_api_key + Content-Type: application/vnd.whispir.message-v1+json + Accept: application/vnd.whispir.message-v1+json + + { + "to" : "John_Wick.1143139@Contact.whispir.sg", + "subject" : "Test SMS Message with tags", + "body" : "Hi @@first_name@@. This is your message." + } + ``` + ``` XML + # To call from a User-defined workspace + POST https://api..whispir.com/workspaces/:workspace_id/messages + # To call from the default workspace + POST https://api..whispir.com/messages + + Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk + x-api-key: your_api_key + Content-Type: application/vnd.whispir.message-v1+xml + Accept: application/vnd.whispir.message-v1+xml + + + + John_Wick.1143139@Contact.whispir.sg + Test SMS Message with tags + Hi @@first_name@@. This is your message. + + ``` + + The main difference with the examples seen so far is given here by the `to` field of the payloads. + + * * * + ## Request Body Details + field | recipients + ---|--- + To | **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 + + * * * + ## Native system tags + When sending messages using the Whispir API, you can automatically include system-generated information via system variables. Each of them will resolve to the value obtained when you send the message. Unlike the preceding ones, they don't depend from the Contacts information stored in Whispir, so they can be included also in messages where the recipients are not represented by their MRI. + + Contact tag| Description| + ---------|---------- + @@dd@@| Current day with leading zero.
For example, 08. + @@mm@@ | Current month with leading zero.
For example, 06. + @@yy@@| Current year, short form.
For example, 22. + @@yyyy@@| Current year, long form.

For example, 2022. + @@day@@ | Day in spoken form.

For example, Wednesday. + @@month@@| Month in spoken form.

For example, January. + @@hrs@@| Current hour with leading zero, in 24 hour format.

For example, 16. + @@min@@ | Current minute with leading zero.

For example, 45. + @@date@ | Current date in format (yyyy-mm-dd)

For example, 2022-02-02. + @@time@@| Current time in 24-hour format.

For example, 16:37. operationId: postMessages parameters: - $ref: '#/components/parameters/x-api-key' From 978460139555752e4fb06cff71b17fa0ec5be0bc Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Fri, 4 Mar 2022 15:33:25 +1100 Subject: [PATCH 13/26] Modified openapi.yaml --- openapi.yaml | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index c8097ca..e21e6c3 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -216,6 +216,172 @@ paths: @@min@@ | Current minute with leading zero.

For example, 45. @@date@ | Current date in format (yyyy-mm-dd)

For example, 2022-02-02. @@time@@| Current time in 24-hour format.

For example, 16:37. + + * * * + ## Message attributes + Whispir’s API customers can simplify their requests by using the message attributes directly from the API. + + Using message attributes allows to achieve flexibility in the communications. With this solution, Developers just need to take care of the data behind a message while the Marketing team can focus on the presentation or messaging channels within the message. + + > Unlike native tags, user-defined attributes require Whispir administrative assistance to enable and are configured at the account level. Please contact your Whispir account manager or the [Whispir Support Team](mailto='support@whispir.com') if interested in using them. Whispir’s API only accepts message attributes containing alpha-numeric ASCII characters. + + We are about to see a full example where an initial fixed message has been adapted to be reusable. + ### Sending an invitation message without message attributes: + ```JSON + POST http://api..whispir.com/messages + + Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk + x-api-key: your_api_key + Content-Type: application/vnd.whispir.message-v1+json + Accept: application/vnd.whispir.message-v1+json + + { + "to" : "jsmith@test.com", + "subject" : "Reminder", + "body" : "Your invitation to the Acme Event will expire on 13/06/2019 at 23:59:59", + "email" : { + "type" : "text/plain", + "body" : "Your invitation to the Acme Event will expire on 13/06/2019 at 23:59:59" + } + } + ``` + ```XML + POST http://api..whispir.com/messages + + Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk + x-api-key: your_api_key + Content-Type: application/vnd.whispir.message-v1+xml + Accept: application/vnd.whispir.message-v1+xml + + + + jsmith@test.com + Reminder + Your invitation to the Acme Event will expire on 13/06/2019 at 23:59:59 + + text/plain + Your invitation to the Acme Event will expire on 13/06/2019 at 23:59:59 + + + ``` + ## Using Templates including attributes + + Using message attributes and message Templates allows developers to cleanly separate these responsibilities. This is done by combining the message channels being used for the message and the data driving the message. + + Under the operational point of view this solution is achieved with two steps: + 1. Creating a Template including attributes + 2. Using the Template and replacing the values for the attributes + + ```JSON + Step 1 - Creating a Template including the attributes + POST http://api..whispir.com/templates + + Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk + x-api-key: your_api_key + Content-Type: application/vnd.whispir.template-v1+json + Accept: application/vnd.whispir.template-v1+json + + { + "messageTemplateName" : "Event Reminder", + "subject" : "Reminder:", + "body" : "Your invitation to the Acme Event will expire on @@event_expiry@@ at @@event_expiry_time@@", + "email" : { + "type" : "text/plain", + "body" : "Your invitation to the Acme Event will expire on @@event_expiry@@." + } + } + + Response - template created + 201 - Created + Location: http://api..whispir.com/templates/DACADB02209CC93C + { + ... + "id": "DACADB02209CC93C", + ... + } + + Step 2 - Using Template including attributes to send the message + POST http://api..whispir.com/messages + + Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk + x-api-key: your_api_key + Content-Type: application/vnd.whispir.message-v1+json + Accept: application/vnd.whispir.message-v1+json + + { + "to" : "jsmith@test.com", + "messageTemplateId" : "DACADB02209CC93C", + "messageattributes" : { + "attribute" : [{ + "name" : "event_expiry", + "value" : "13/06/2019" + },{ + "name" : "event_expiry_time", + "value" : "23:59:59" + }] + } + } + ``` + ```XML + Step 1 - Creating a Template including attributes + POST http://api..whispir.com/templates + + Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk + x-api-key: your_api_key + Content-Type: application/vnd.whispir.template-v1+xml + Accept: application/vnd.whispir.template-v1+xml + + + + Event Reminder + Reminder + Your invitation to the Acme Event will expire on @@event_expiry@@ at @@event_expiry_time@@ + + text/plain + Your invitation to the Acme Event will expire on @@event_expiry@@ at @@event_expiry_time@@ + + + + Response - template created + 201 - Created + Location: http://api..whispir.com/templates/DACADB02209CC93C + + + ... + DACADB02209CC93C + ... + + + Step 2 - Using Template including attributes to send the message + POST http://api..whispir.com/messages + + Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk + x-api-key: your_api_key + Content-Type: application/vnd.whispir.message-v1+xml + Accept: application/vnd.whispir.message-v1+xml + + + + jsmith@test.com + DACADB02209CC93C + + + + @@event_expiry@@ + 13/06/2019 + + + @@event_expiry_time@@ + 23:59:59 + + + + + ``` + + Using this message template ID and now using the message attribute @@event_expiry@@, the updated code example (combining the message template and message attribute) is far simpler to implement and is more efficient. operationId: postMessages parameters: - $ref: '#/components/parameters/x-api-key' From 21f18ace3f099c37d8632373676be6a5b71ea28f Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Mon, 7 Mar 2022 11:33:13 +1100 Subject: [PATCH 14/26] Modified openapi.yaml --- openapi.yaml | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 118 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index e21e6c3..886bca6 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -78,7 +78,7 @@ paths: tags: - Messages summary: Send a message - description: |- + description: | Communications are the core of what the Whispir Platform API offers as a service to customers. Whispir has the ability to send communications across 7 different channels in a single API request: - **SMS** - up to 1600 characters per message, premium routes, delivery receipts @@ -382,6 +382,123 @@ paths: ``` Using this message template ID and now using the message attribute @@event_expiry@@, the updated code example (combining the message template and message attribute) is far simpler to implement and is more efficient. + + * * * + ## Scheduled message delivery + ### Timezone - Scheduling rules + Using the Whispir API you can schedule messages to be sent later, both once or repeatedly with the possibility to specify the interval between the sessions. The service is available for SMS, email, voice, rich messages + + 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 + # To send from a User-defined workspace + POST https://api..whispir.com/workspaces/:workspace_id/messages + # To send from the default workspace + POST https://api..whispir.com/messages + + Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk + x-api-key: your_api_key + Content-Type: application/vnd.whispir.message-v1+json + Accept: application/vnd.whispir.message-v1+json + + ONCE + In this sample we will schedule a single message to be delivered at 3:55pm on 14 February 2019 + + { + "to" : "jsmith@test.com", + "subject" : "Test scheduled email message", + "email" : { + "body" : "This is my scheduled content", + "type" : "text/plain" + }, + "messageType" : "SCHEDULED", + "scheduleType" : "ONCE", + "scheduleDate" : "14/02/2019 15:55" + } + + REPEAT + In this sample we will will schedule 10 messages to be delivered every hour starting from 3:55pm on 14 February 2019 + + { + "to" : "jsmith@test.com", + "subject" : "Test scheduled email message", + "email" : { + "body" : "This is my scheduled content", + "type" : "text/plain" + }, + "messageType" : "SCHEDULED", + "scheduleType" : "REPEAT", + "scheduleDate" : "14/02/2019 15:55", + "repetitionCount" : "10", + "repeatDays" : "0", + "repeatHrs" : "1", + "repeatMin" : "0" + } + ``` + ```XML + # To send from a User-defined workspace + POST https://api..whispir.com/workspaces/:workspace_id/messages + # To send from the default workspace + POST https://api..whispir.com/messages + + Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk + x-api-key: your_api_key + Content-Type: application/vnd.whispir.message-v1+json + Accept: application/vnd.whispir.message-v1+json + + ONCE + In this sample we will schedule a single message to be delivered at 3:55pm on 14 February 2019 + + + + john.smith@test.com + Test scheduled email message + + This is my scheduled content + text/plain + + SCHEDULED + ONCE + 14/02/2019 15:55 + + + REPEAT + In this sample we will will schedule 10 messages to be delivered every hour starting from 3:55pm on 14 February 2019 + + + + john.smith@test.com + Test scheduled email message + + This is my scheduled content + text/plain + + SCHEDULED + REPEAT + 14/02/2019 15:55 + 10 + 0 + 1 + 0 + + ``` + ### Request Body Details + In addition to the parameters already specified for each of the channels of interest the following ones are the ones related to the scheduling: + + Parameter| Description| + ---------|---------- + messageType **(required)**| To be set to "SCHEDULED" in order to start the scheduling. + scheduleType **(required)** | To be set either to "ONCE" or "REPEAT", depending on the messaging policy to be adopted. + scheduleDate **(required)**| For scheduled one-off messages it specifies the date to trigger the single delivery. For scheduled messages meant to be sent multiple times it determines the moment in which the first of them will be sent. + repetitionCount| Specifies how many times the scheduled message will be sent to the recipient. When omitted its value will be set to 1 by default. + repeatDays |It specifies the interval in days between each repetition. It can be combined with the other "repeat" parameters. It can be omitted if equal to zero, but in this case it must be ensured that at least one of the other "repeat" parameters is non-zero. + repeatHrs| It specifies the interval in hours between each repetition. It can be combined with the other "repeat" parameters. It can be omitted if equal to zero, but in this case it must be ensured that at least one of the other "repeat" parameters is non-zero. + repeatMin| It specifies the interval in minutes between each repetition. It can be combined with the other "repeat" parameters. It can be omitted if equal to zero, but in this case it must be ensured that at least one of the other "repeat" parameters is non-zero. operationId: postMessages parameters: - $ref: '#/components/parameters/x-api-key' From 39be902bb30572eb763ed0dddda2cc466bb0610f Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Mon, 7 Mar 2022 11:41:59 +1100 Subject: [PATCH 15/26] Modified toc.json --- toc.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/toc.json b/toc.json index c7ecb0f..289d2bf 100644 --- a/toc.json +++ b/toc.json @@ -46,7 +46,7 @@ }, { "type": "divider", - "title": "Message types" + "title": "Advanced message features" }, { "type": "item", From d9418a728373d126ef6f4c8969acfa4d5777fd2a Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Mon, 7 Mar 2022 12:16:00 +1100 Subject: [PATCH 16/26] Modified openapi.yaml --- openapi.yaml | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 886bca6..289326e 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -85,7 +85,7 @@ paths: - **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 - - **WhatsApp** - customised WhatsApp messages featuring mutliple content types + - **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 @@ -4500,12 +4500,12 @@ components: properties: type: type: string - minLength: 1 - description: 'The type of WhatsApp message to be sent, e.g. "template".' + description: The type of WhatsApp message to be sent. + enum: + - template name: type: string - minLength: 1 - description: Internal name for message e.g. "aue_image_quick_reply". + 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. @@ -4516,9 +4516,15 @@ components: $ref: '#/components/schemas/whatsapp_header' body: type: array - description: 'Message body is an array of strings. Each string should be labeled ''text''. Each string will appear as one line of text in WhatsApp messasge (see example). Minimum 1 string required. ' + description: Message body is an array of text objects. Each object represents 1 variable field in the WhatsApp template. items: - type: string + type: object + minProperties: 1 + properties: + text: + type: string + required: + - text buttons: type: array description: An array of whatsapp_button objects. Each object represents one button in the WhatsApp message. From dda5069b57233a9730273845a501848f6ef0d669 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Mon, 7 Mar 2022 12:34:26 +1100 Subject: [PATCH 17/26] Modified 3 files --- docs/Message types/WhatsApp-messages.md | 163 ++++++++---------------- openapi.yaml | 32 +++-- toc.json | 9 -- 3 files changed, 72 insertions(+), 132 deletions(-) diff --git a/docs/Message types/WhatsApp-messages.md b/docs/Message types/WhatsApp-messages.md index 0092705..0c03f1a 100644 --- a/docs/Message types/WhatsApp-messages.md +++ b/docs/Message types/WhatsApp-messages.md @@ -1,107 +1,15 @@ +--- +internal: true +--- + # WhatsApp messages ## Overview -Customers can send templated WhatsApp messages via Whispir's API. +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. -### WhatsApp structured data object - -This object can sent via a `POST` call to the `/messages` endpoint. - -The JSON schema for the 'whatsapp' object is s as follows: - -```json json_schema -{ - "object": "whatsapp": { - "description": "This object is a WhatsApp message payload to be used with the POST /messages method.", - "type": "object", - "properties": { - "type": { - "type": "string", - "minLength": 1, - "description": "The type of WhatsApp message to be sent, e.g. \"template\"." - }, - "name": { - "type": "string", - "minLength": 1, - "description": "Internal name for message e.g. \"aue_image_quick_reply\"." - }, - "content": { - "type": "object", - "description": "The WhatsApp message payload.", - "required": [ - "body" - ], - "properties": { - "header": { - "type": "object", - "description": "Optional header for a Whatsapp message.", - "properties": { - "image": { - "type": "string", - "description": "Link to image location." - }, - "video": { - "type": "string", - "description": "Link to video location." - }, - "document": { - "type": "string", - "description": "Link to document location." - }, - "location": { - "type": "string", - "description": "“Longitude”, \"latitude\", \"name\", and \"address\"." - } - } - }, - - "body": { - "type": "array", - "description": "Message body is an array of strings. Each string should be labeled 'text'. Each string will appear as one line of text in WhatsApp messasge. Minimum 1 string required. ", - "items": { - "type": "string" - } - }, - "buttons": { - "type": "object", - "description": "Optional button object for a WhatsApp message. Multiple buttons can be added when placed in an array.", - "properties": { - "index": { - "type": "string" - }, - "sub_type": { - "type": "string", - "description": "The type of dynamic button i.e. \"quick reply\" or \"url\"." - }, - "text": { - "type": "string", - "description": "Required if sub_type = url. The url destination when the button is clicked." - }, - "payload": { - "type": "string", - "description": "Required if sub_type = quick reply. Name of the quick reply buttons configured within your WhatsApp Business Manager account." - } - }, - "required": [ - "index", - "sub_type" - ] - } - } - } - }, - "required": [ - "type", - "name", - "content" - ] - } -} -``` - ## How to query sent message status using WhatsApp's API /status endpoint ### WhatsApp API: GET message status @@ -123,7 +31,9 @@ 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: @@ -132,6 +42,7 @@ Authorisation: Bearer ``` ### hatsApp API: Query messages by sender number (from_phone_number) + ```json GET: https://whatsapp.ap1.whispir.com/status?sender=61430430 Headers: @@ -140,6 +51,7 @@ Authorisation: Bearer ``` ### WhatsApp API: Query messages by recipient number (to_phone_number) + ```json GET: https://whatsapp.ap1.whispir.com/status?recipient=61430430 Headers: @@ -148,23 +60,29 @@ 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 [ { @@ -194,16 +112,21 @@ Authorisation: Bearer "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", @@ -213,11 +136,13 @@ Authorisation: Bearer "parameter": "{\"parameter_count\":0,\"parameter_data\":[]}" } ``` -** required fields: "name", "whatsappId","content" -** "name": must be low case, number and underscore -** "name": maximum 30 characters + +\*\* required fields: "name", "whatsappId","content" +\*\* "name": must be low case, number and underscore +\*\* "name": maximum 30 characters ### Sample response + ```json { "id": "17", @@ -233,28 +158,36 @@ Authorisation: Bearer "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 + +### 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", @@ -270,8 +203,11 @@ Authorisation: Bearer "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", @@ -281,7 +217,9 @@ Authorisation: Bearer "parameter": "{\"parameter_count\":0,\"parameter_data\":[]}" } ``` + #### Sample response + ```json { "id": "17", @@ -297,15 +235,20 @@ Authorisation: Bearer "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 @@ -313,14 +256,14 @@ Following query parameters are supported: - 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 +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 | \ No newline at end of file +| Column A | Column B | +| -------- | -------- | +| A1 | B1 | +| A2 | B2 | +| A3 | B3 | diff --git a/openapi.yaml b/openapi.yaml index 289326e..5e0851d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4487,7 +4487,7 @@ components: name: fieldMapping title: Field Mapping whatsapp: - description: This object is a WhatsApp message payload to be used with the POST /messages method. + description: A structured WhatsApp channel payload. type: object x-examples: hello-world: @@ -4534,6 +4534,7 @@ components: - type - name - content + title: WhatsApp whatsapp_header: title: whatsapp_header type: object @@ -4558,43 +4559,48 @@ components: image: type: string description: Link to image location. + format: uri video: type: string description: Link to video location. + format: uri document: type: string description: Link to document location. + format: uri location: type: string description: '“Longitude”, "latitude", "name", and "address".' + format: uri whatsapp_button: title: whatsapp_button type: object - description: Optional button object for a WhatsApp message. + 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 i.e. "quick reply" or "url". text: type: string - description: Required if sub_type = url. The url destination when the button is clicked. + description: The url destination when the button is clicked. Required if sub_type = url. payload: type: string - description: Required if sub_type = quick reply. Name of the quick reply buttons configured within your WhatsApp Business Manager account. + description: 'Name of the quick reply buttons configured within your WhatsApp Business Manager account. Required if sub_type = quick reply. ' required: - index - sub_type - 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' parameters: x-api-key: name: x-api-key diff --git a/toc.json b/toc.json index 289d2bf..d2a606a 100644 --- a/toc.json +++ b/toc.json @@ -43,15 +43,6 @@ "type": "item", "title": "Whispir API Postman Collection", "uri": "docs/Getting started/Whispir-API-Postman-Collection.md" - }, - { - "type": "divider", - "title": "Advanced message features" - }, - { - "type": "item", - "title": "WhatsApp messages", - "uri": "docs/Message types/WhatsApp-messages.md" }, { "type": "divider", From ea99398289b1e5f6ce1e8d75b9c69707ba36016b Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Mon, 7 Mar 2022 12:46:07 +1100 Subject: [PATCH 18/26] Modified openapi.yaml --- openapi.yaml | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 5e0851d..50d02ea 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4560,18 +4560,43 @@ components: 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: string + type: object description: '“Longitude”, "latitude", "name", and "address".' format: uri + properties: + longitude: + example: '-122.425332' + type: integer + description: Location longitude. + latitude: + type: integer + example: 37.758056 + description: Location latitude + name: + type: string + example: Facebook HQ + description: Location name. + address: + type: string + description: Location address + example: '1 Hacker Way, Menlo Park, CA 94025' + required: + - longitude + - latitude + - name + - address whatsapp_button: title: whatsapp_button type: object From d638ed8a94093aff4a4c17d3680e9e9f8bc87973 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Mon, 7 Mar 2022 12:51:57 +1100 Subject: [PATCH 19/26] Modified openapi.yaml --- openapi.yaml | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 50d02ea..3137add 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4573,25 +4573,28 @@ components: example: 'https://s3-eu-west-1.amazonaws.com/hughhopkins.co.uk/sample_media/Sf+flight+itinerary.pdf' location: type: object - description: '“Longitude”, "latitude", "name", and "address".' - format: uri + description: A location for the header. properties: longitude: - example: '-122.425332' type: integer + example: -122.425332 description: Location longitude. + minimum: -180 + maximum: 180 latitude: type: integer example: 37.758056 - description: Location latitude + description: Location latitude. + minimum: -90 + maximum: 90 name: type: string example: Facebook HQ description: Location name. address: type: string - description: Location address example: '1 Hacker Way, Menlo Park, CA 94025' + description: Location street address. required: - longitude - latitude From 371a61167fbc7caa125c45707d23b5905df27bd1 Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Mon, 7 Mar 2022 12:56:56 +1100 Subject: [PATCH 20/26] Modified openapi.yaml --- openapi.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 3137add..3a990bb 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4497,6 +4497,7 @@ components: body: - text: hello - text: world + title: WhatsApp properties: type: type: string @@ -4516,13 +4517,14 @@ components: $ref: '#/components/schemas/whatsapp_header' body: type: array - description: Message body is an array of text objects. Each object represents 1 variable field in the WhatsApp template. + description: Message body is an array of text objects. Each object is inserted into a variable field in the WhatsApp message template. 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: @@ -4534,7 +4536,6 @@ components: - type - name - content - title: WhatsApp whatsapp_header: title: whatsapp_header type: object From f75b4943adcde730fcca2870bbb1f81d0d4553ec Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Mon, 7 Mar 2022 12:57:19 +1100 Subject: [PATCH 21/26] Modified openapi.yaml --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 3a990bb..13023c7 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4517,7 +4517,7 @@ components: $ref: '#/components/schemas/whatsapp_header' body: type: array - description: Message body is an array of text objects. Each object is inserted into a variable field in the WhatsApp message template. + description: Message body is an array of text objects. items: type: object minProperties: 1 From fe27589da79bac0eebb33c60f46d38e1241dee6c Mon Sep 17 00:00:00 2001 From: "jzcummings@whispir.com" Date: Mon, 7 Mar 2022 12:58:12 +1100 Subject: [PATCH 22/26] Modified openapi.yaml --- openapi.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 13023c7..0123b76 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4620,7 +4620,10 @@ components: description: The index of the object in the array. sub_type: type: string - description: The type of dynamic button i.e. "quick reply" or "url". + 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. From aa6690231e91d96eba7ec0c3008d9a6ae835d504 Mon Sep 17 00:00:00 2001 From: Richard Fontein <32132657+richardfontein@users.noreply.github.com> Date: Fri, 1 Apr 2022 14:31:20 +1100 Subject: [PATCH 23/26] Revert scheduled message changes --- openapi.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 7504559..f3ef613 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -367,12 +367,19 @@ paths: ### Scheduled Messages #### Timezone - Scheduling rules + + Using the Whispir API you can schedule messages to be sent later, both once or repeatedly with the possibility to specify the interval between the sessions. The service is available for SMS, email, voice, rich messages + 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 Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk x-api-key: your_api_key Content-Type: application/vnd.whispir.message-v1+json Accept: application/vnd.whispir.message-v1+json - ONCE In this sample we will schedule a single message to be delivered at 3:55pm on 14 February 2019 { @@ -386,7 +393,6 @@ paths: "scheduleType" : "ONCE", "scheduleDate" : "14/02/2019 15:55" } - REPEAT In this sample we will will schedule 10 messages to be delivered every hour starting from 3:55pm on 14 February 2019 { @@ -415,7 +421,6 @@ paths: ONCE In this sample we will schedule a single message to be delivered at 3:55pm on 14 February 2019 - john.smith@test.com @@ -428,7 +433,6 @@ paths: ONCE 14/02/2019 15:55 - REPEAT In this sample we will will schedule 10 messages to be delivered every hour starting from 3:55pm on 14 February 2019 From 9d974b4ca00843fd61a542a84676e4642e4f7a27 Mon Sep 17 00:00:00 2001 From: Richard Fontein <32132657+richardfontein@users.noreply.github.com> Date: Fri, 1 Apr 2022 14:32:08 +1100 Subject: [PATCH 24/26] Revert scheduled messages changes --- openapi.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index f3ef613..98e2126 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -365,9 +365,7 @@ paths: * * * ### Scheduled Messages - #### Timezone - Scheduling rules - Using the Whispir API you can schedule messages to be sent later, both once or repeatedly with the possibility to specify the interval between the sessions. The service is available for SMS, email, voice, rich messages 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 @@ -418,7 +416,6 @@ paths: x-api-key: your_api_key Content-Type: application/vnd.whispir.message-v1+json Accept: application/vnd.whispir.message-v1+json - ONCE In this sample we will schedule a single message to be delivered at 3:55pm on 14 February 2019 From fed00ea6c12e488ed6a26848d48d3bc7c8424332 Mon Sep 17 00:00:00 2001 From: Richard Fontein <32132657+richardfontein@users.noreply.github.com> Date: Fri, 1 Apr 2022 14:33:40 +1100 Subject: [PATCH 25/26] Revert scheduled messages changes --- openapi.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 98e2126..f7f7342 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -365,7 +365,9 @@ paths: * * * ### Scheduled Messages + #### Timezone - Scheduling rules + Using the Whispir API you can schedule messages to be sent later, both once or repeatedly with the possibility to specify the interval between the sessions. The service is available for SMS, email, voice, rich messages 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 From 34a4d1b532d4dae943940dd8b4f4e4a9ef73cdf2 Mon Sep 17 00:00:00 2001 From: rfontein Date: Fri, 1 Apr 2022 16:55:31 +1300 Subject: [PATCH 26/26] Resolve conflicts --- openapi.yaml | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index f7f7342..f4a8571 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -365,7 +365,7 @@ paths: * * * ### Scheduled Messages - + #### Timezone - Scheduling rules Using the Whispir API you can schedule messages to be sent later, both once or repeatedly with the possibility to specify the interval between the sessions. The service is available for SMS, email, voice, rich messages @@ -470,7 +470,6 @@ paths: application/vnd.whispir.bulkmessage-v1+xml: schema: $ref: '#/components/schemas/message' - description: 'Message object needed to create message. At least one of the Body fields must be populated [SMS, email, voice, web or whatsapp].' examples: SMS: value: @@ -7588,7 +7587,7 @@ components: description: A structured WhatsApp channel payload. type: object x-examples: - hello-world: + Example: type: icebreaker name: igniteagain content: @@ -7675,17 +7674,13 @@ components: description: A location for the header. properties: longitude: - type: integer example: -122.425332 description: Location longitude. - minimum: -180 - maximum: 180 + type: number latitude: - type: integer + type: number example: 37.758056 description: Location latitude. - minimum: -90 - maximum: 90 name: type: string example: Facebook HQ