Hermes API 1 - ages.pucrs.br · Hermes API 1.0 Login and Authentication To authenticate yourself...

Hermes API 1.0 - Specification

Document Version: 1.6 1

HERMES API 1.0 - Specification

2018



Version Name Date Description

1.0 Gustavo Mistrinelli 21/06/2018 Start of specification

1.1 Gustavo Mistrinelli 01/07/2018 Minor updates

1.2 Gustavo Mistrinelli 10/08/2018 Minor fix and updates

1.3 Gustavo Mistrinelli 17/08/2018 File sending updates

1.4 Gustavo Mistrinelli 20/08/2018 Minor fix updates

1.5 Gustavo Mistrinelli 28/08/2018 Fix send message JSON

1.6 Gustavo Mistrinelli 30/08/2018 Minor fix updates



Hermes API 1.0

Login and Authentication

To authenticate yourself with Hermes API, you must log in. To log in, you send your username and password inside the body and receive a bearer token in response. You then use the bearer token for authentication when sending requests to any Hermes API endpoint. Standard Login After you have set a new password, you can use a standard login for the Hermes API client, which should look like:

POST /api/v1/users/sign_in { "username":"<<api_username>>", "password":"<<api_password>>" }

Login Responses When your login request is received by the Hermes API client, your credentials are processed for validation.

• If successful, your token is generated. The response contains your token in the jwt field. • If not successful, an error is returned.

Success On success, a status of 200 OK is returned, along with the token. The response will look like the following example:

{ "jwt":"eyJhbGciOHlXVCJ9.eyJ1c2VyIjoNTIzMDE2Nn0.mEoF0COaO00Z1cANo" }

Parameters

Field Required Default Value/Description

jwt Yes Authentication token to be used for all other Hermes API calls. The token must be sent in the authorization header in the format: Authorization: Bearer <authentication-token>



Error

If the request is not successful, you will see an HTTP status of 401 Unauthorized. This error generally means that the username and/or password that was sent with the login request is invalid, and thus the Hermes API client is unable to generate the token.

Tokens For your initial login, use your username and password for authentication. For all other secure interactions, you must use the bearer token that is returned after a successful login. IMPORTANT: Token will expire after 10 days. You need to sign in again to obtain a token to continue using this API. Usage The tokens are sent in the authorization header of the HTTP request for many of the Hermes API calls. In particular, notice in the following example that the type of authorization that is used with this token is Bearer.

HTTP-METHOD /secured-path Authorization: Bearer your-auth-token

For all secured paths, we validate the token. During validation, if a token is found to be expired, that token is removed from the system. Upon successful validation, the request is allowed to proceed. Requests made with an invalid token receive a 401 Unauthorized error code.



Send Messages API

Use the Messages API to send messages to your customers. This API enables you to send text and media messages.

This kind of messages are only allowed within a window of 24 hours after customer contact. After this window, an error message will be presented and the only way to communicate with our customer will be using HSM messages.

The media_id parameter is an identifier that is generated when the number is activated on Hermes platform.

Requests

The endpoint to send a message is /api/v1/messages. The following shows the sample format of the message request:

POST api/v1/messages { "message": { "to": "+5511987654321", "type": "text", "text": "message_content”, "media_id": "<<media_id>>” } }

Sending Files POST api/v1/messages {



"message": { "to": "+5511987654321", "recipient_type": "individual", "type": "document", "content_type": "document/pdf", "media_id": "<<media_id>>”, "url": "https://url.com/documento.pdf", "caption": "NOTE testing document" } }

Field Required Default Value/Description

caption No File note or description

url Yes File URL

type Yes document image audio

content_type Yes image/jpeg image/png image/gif image/bmp image/webp document/doc document/docx document/ppt document/pptx document/xls document/xlsx audio/AAC audio/M4A audio/AMR audio/MP3 audio/OGG audio/OPUS

Responses The following section shows an example of payload in message API response.

{ "message": {



"id": "message_id" } }



Sending a HSM (Highly Structured Message) As with other messages, the message is sent to the /v1/messages endpoint. What's different about sending HSMs is the content of the message body specified with the hsm parameter.

The hsm parameter contains a namespace and an element_name pair that identify a template and the values to apply to variables in that template.

The following code provides an example of sending an HSM message. This example uses the purchase_with_credit_card element name within the whatsapp:hsm:ecommerce namespace.

POST /v1/messages { message: "to": "whatsapp_number", "type": "hsm", "hsm": { "namespace": "whatsapp:hsm:ecommerce" "element_name": "purchase_with_credit_card", "language": { "policy": "fallback" | "deterministic", "code": "en_US" } "localizable_params": [ { "default": "$10" }, { "default": "1234" } ], } }

The resulting message received by the customer will look like this:

You made a purchase for $10 using a credit card ending in 1234.

As you can see from looking at the localizable parameters and the message the client received, the template used the default value of 10 as the amount of the purchase and the default value of 1234 as the last numbers of the account. Parameters

Name Required Description

type Yes (for HSM)

The type of message being sent. Default: text Other options: image, audio, document, hsm




to Yes The WhatsApp ID or group ID to whom the message is being sent.

recipient_type No (Optional)

Default: individual

hsm Yes (for HSM)

The containing element for the message content. Indicates that the message is highly structured. Parameters contained within provide the structure.

The hsm object Name Required Description

namespace Yes The namespace that contains the element_name that will be used. For Hermes API, namespace is: 8a377124_6ae6_7e6d_e6f3_05cc46a5d612

element_name Yes The element name that indicates which template to use within the namespace.

language Yes Allows for the specification of a deterministic or fallback language.

localizable_params Yes This field is an array of values to apply to variables in the template.

Language

The language parameter sets the language policy for an HSM; you can set it to either fallback or deterministic.

Parameters


policy Yes The language policy the message should follow. Values: fallback or deterministic

code Yes The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and PT_BR).



Localizable Parameters

When sending an HSM, the hsm object is required. To define Highly Structured Messages, you specify a namespace and an element_name pair that identify a template. Templates have parameters that will be dynamically incorporated into the message. For the example used in this document, the template message looks like this:

"You made a purchase for {{1}} using a credit card ending in {{2}}."

For "namespace": "whatsapp:hsm:ecommerce" with "element_name": "purchase_with_credit_card", the first value you list replaces the {{1}} variable in the template message and the second value you list replaces the {{2}} variable.

Note that the number of parameters passed into the payload must match the number of parameters in the hsm object. If not, you will get a callback informing you that there was an issue displaying the HSM. Some of these parameters (e.g., date-time or currency) are localizable so that they are displayed appropriately based on the customer's language and locale preferences. If the device is unsuccessful in localizing a parameter, it will fallback to the value that is provided as the "default" value.

Parameters

Name Type Required Description

default String Yes Default text if localization fails.

currency currency object No If the currency object is used, it contains required parameters currency_code and amount_1000.

date_time date_time object No If the date_time object is used, further definition of the date and time is required. See the example below for two of the options.

All of the localization parameters must have a default value. The default value is all that is needed when you are specifying text.

However, to specify currency and date in addition to the default, when applicable, use the currency and date_timeobjects, as shown below. This will allow the client to attempt to



localize this data the best way possible and fallback to the "default" option only if they cannot localize the data. Note that using the currency and date_time` objects for appropriate parameters is highly recommended to enable an optimal localized experience for your customers.

The following is a complete example that demonstrates the use of all of the currently supported localized types:

{ "message": { "to": "+5511987654321", "type": "hsm", "recipient_type": "individual", "hsm": { "namespace": "whatsapp:hsm:banks:bigbank1", "element_name": "four_lparam_demo", "language": { "policy": "deterministic", "code": "en_US" } "localizable_params": [ { "default": "just a string" }, { "default": "$100.99", "currency": { "currency_code": "USD", "amount_1000": 100990 } }, { "default": "February 25, 1977", "date_time": { "component": { "day_of_week": 5, "day_of_month": 25, "year": 1977, "month": 2, "hour": 15, "minute": 33 }



} }, { "default": "January 26, 2017", "date_time": { "unix_epoch": { "timestamp": 1485470276 } } } ] } } }

Response

A successful response includes a messages object with an id.

{ "messages": [{ "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU" }] }



Webhook Notification Messages

When is activated your number, you need to provide a Webhook URL that will be used to notified you when a new message or status of a sent message is received.

Format of the Notifications Webhook

The format of the text notifications Webhook is shown below. The following sections provide more detail for message and notification.

Text Message format

POST / { "messages": [ { "from": "sender_wa_id", "id": "message_id", "timestamp": "message_timestamp", "type": "text", # Only in case of error, errors field (array) will be present "errors": [ { ... } ], "text": { "body": "text message content" } ] }

Status Message format

POST / { "statuses": [ { "id": "message_id", "recipient_id": "sender_wa_id", "status": "sent|delivered|read", "timestamp": "message_timestamp" }



] }

Example: Message Failed

{ "statuses": [{ "errors": [{ "code": 470, "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider." }], "id": "gBGGEgZHMlEfAgkM1RBkhDRr7t8", "recipient_id": "12064001000", "status": "failed", "timestamp": "1533332775" }] }

All Possible Outbound Message Statuses This table lists all possible options for the status of an outbound message.

Status Description WhatsApp Mobile Equivalent

sent Message received by WhatsApp server

One checkmark

delivered Message delivered to recipient

Two checkmarks

read Message read by recipient Two blue checkmarks

failed Message failed to send Red error triangle



Webhook Examples

Incoming webhook: {"messages":[{"from":"1234567890","id":"ABGGhSkIc2B_Ago-sDy5BNm-1gI5","text":{"body":"Hi"},"timestamp":"1529381066","type":"text"}]}

Incoming webhook: {"statuses":[{"id":"gBGGhSkIc2B_AgkXDygfSDwgG5s","recipient_id":"1234567890","status":"sent","timestamp":"1529381072"}]}

Incoming webhook: {"statuses":[{"id":"gBGGhSkIc2B_AgkXDygfSDwgG5s","recipient_id":"1234567890","status":"delivered","timestamp":"1529381072"}]}

Incoming webhook: {"statuses":[{"id":"gBGGhSkIc2B_AgkXDygfSDwgG5s","recipient_id":"1234567890","status":"read","timestamp":"1529381076"}]}

Hermes API 1 - ages.pucrs.br · Hermes API 1.0 Login and Authentication To authenticate yourself...

Documents

Transcript of Hermes API 1 - ages.pucrs.br · Hermes API 1.0 Login and Authentication To authenticate yourself...