Webservices to manage webhooks

Webservices to manage webhooks

Webhooks

/webhook/webhooks

Webhooks are user-defined HTTP callbacks that are triggered by specific events. Whenever that trigger event occurs, the WhatsApp Business API client sees the event, collects the data, and immediately sends a notification (HTTP request) to the Webhook URL specified in the webhooks endpoint that indicates when you receive a message or updates the status of the sent message.

This document covers:
  1. Prerequisites
  2. Requests
    1. Create
    2. Get
    3. Update
    4. Delete
  3. Error responses
  4. Format of the notifications webhook
    1. Text message
    2. Alert

Prerequisites

  1. Woztell account activated
  2. To use the Woztell API, you must first authenticate yourself and receive a token that enables you to access the service. Contact support@woztell.com for more information on how to do this.

Requests

When a customer sends you a message, the Woztell API client will send an HTTP POST request notification to the Webhook URL with the details that are described in the following document.
It is important that your Webhook returns an HTTPS 200 OK response to notifications. Otherwise, the Woztell API client will consider that notification as failed and will not try again.

Endpoint:

Parameters:

Parameter name

Data type

Description

Possible Values

WOZTELL_ADMIN*

String

Email address of your Woztell account.

admin@company.com

WOZTELL_TOKEN*

String

Your Woztell account token.

abc-defgh-ijk-123

WOZTELL_NUMBER*

String

Woztell phone number validated by WhatsApp.

"+1-631-555-1002", "16315551002", "001(631)555-1002"or "1 631 555 1002" 

DATA
JSON
See the following documentation in Data parameters section.

*Parameter required 

Create

Create a new webhook
POST https://webservice.woztell.com/webhook/webhooks
{
 "WOZTELL_ADMIN":"your-woztell-admin-email",
 "WOZTELL_TOKEN":"your-woztell-token",
	"WOZTELL_NUMBER":"your-woztell-number",
 "DATA":
  {
         "URL":"notifications-webhook-url",
         "LABEL":"your-label-text",
         "ENABLED":"boolean",
         "MESSAGES":"boolean",
         "ALERTS":"boolean"
  }
}      

DATA parameters:

Parameter name

Data type

Description

Possible Values

URL*

String

The webhook URL to send messages

"https://myserver.com/webhook" 

LABEL*

String

A label for you to keep track of what this webhooks is for

"Zoho flow notifications"

ENABLED
Boolean
If the webhook is active. Default value is true
true or false
MESSAGES
Boolean
If you want to receive text messages in webhook. Default value is true.
true or false
ALERTS
Boolean
If you want to receive alerts of outbound messages. Default value is false.
true or false
IMAGES
Boolean
If you want to receive incoming images. The default value is false
true or false
 *Parameter required

Response

{
 "STATUS":"SUCCESS",
 "ID":"webhook-id"
}

Get

Get a webhook
GET https://webservice.woztell.com/webhook/webhooks
{
 "WOZTELL_ADMIN":"your-woztell-admin-email",
 "WOZTELL_TOKEN":"your-woztell-token",
 "WOZTELL_NUMBER":"your-woztell-number",
 "DATA":
  {
           "ID":"webhook-id"
  }
}

DATA parameters:

Parameter name

Data type

Description

Possible Values

ID

String

Webhook ID. If the ID is not specified, all webhooks will be returned.

"123123413" 

Response

{
 "STATUS":"SUCCESS",
 "DATA":[
	{
            "ID":"webhook-id",
            "URL":"notifications-webhook-url",
             "LABEL":"your-label-text",
            "ENABLED":"boolean",
            "MESSAGES":"boolean",
            "ALERTS":"boolean"
  },
{

               "ID":"webhook-id",
               "URL":"notifications-webhook-url",
              "LABEL":"your-label-text",
              "ENABLED":"boolean",
               "MESSAGES":"boolean",
               "ALERTS":"boolean"
  },...
	]
}

Update

Update a webhook
POST https://webservice.woztell.com/webhook/webhooks
{
 "WOZTELL_ADMIN":"your-woztell-admin-email",
 "WOZTELL_TOKEN":"your-woztell-token",
 "WOZTELL_NUMBER":"your-woztell-number",
 "DATA":
  {
			"ID" : "webhook-id"
   "URL":"notifications-webhook-url",
   "LABEL":"your-label-text",
   "ENABLED":"boolean", 
			"MESSAGES":"boolean",
			"ALERTS":"booleas"
   }
}
DATA parameters:

Parameter name

Data type

Description

Possible values

ID*

String

Webhook ID

"123123413"

URL

String

Your Woztell account token.

"https://myserver.com/webhook"

LABEL
String
A label for you to keep track of what this webhooks is for
"Zoho Flow notification"
ENABLED
Boolean
If the webhook is active
True or false
*Parameter required

Response

{
 "STATUS":"SUCCESS",
 "ID":"webhook-id"
}

Delete

Delete a webhook
DELETE https://webservice.woztell.com/webhook/webhooks
{
 "WOZTELL_ADMIN":"your-woztell-admin-email",
 "WOZTELL_TOKEN":"your-woztell-token",
 "WOZTELL_NUMBER":"your-woztell-number",
 "DATA":
  {
   "ID":"webhook-id"
  }
}
DATA parameters:

Parameter name

Data type

Description

Possible values

ID*

String

Webhook ID

"123123413"

*Parameter required

Response

{
 "STATUS":"SUCCESS",
 "ID":"webhook-id"
}

Error Responses

See the following document for more information about the following types of error and status messages:

STATUS

DESCRIPTION

ERROR

             METHOD NOT ALLOWED

ERROR

             INVALID AUTHORIZATION

ERROR

             INVALID JSON DATA

ERROR

             NO WHATSAPP ACTIVED

ERROR

             Other error details


{
	"STATUS":"ERROR",
	"DESCRIPTION":"INVALID JSON DATA"
}

Format of the Notifications webhook

Messages
When a customer sends you a message, the Woztell API client will send an HTTP POST request notification to the Webhook URL in the following format:
{
        "id":"WhatsApp-message-id",
	"from":"from-WhatsApp-phone",
	"to":"to-WhatsApp-phone",
	"type":"text",
	"timestamp":"timestamp-for-WhatsApp-message",
	"text":"text-WhatsApp-message"
}            
Parameters:

Parameter name

Data type

Description

Possible values

ID

String

WhatsApp message ID

"ABGHVJNHZYFRPwIQtAkyZ4zvbaRCCwqa1ekDuQ"

from
String
The issuer's WhatsApp number in international format.
"0019875632588"
to
String
The receiver's WhatsApp number.
"0034675572588"
type
String
Type of message. "text" is the only possible value.
"text"
timestamp
Number
Time when the message was sent. Timestamp is in seconds
"1593554400"
text
String
WhatsApp message text
"Hello world"


Alerts

When you send a message to a phone number, the Woztell API client will send an HTTP POST request notification to the Webhook URL in the following format:
{
 	"id":"WhatsApp-message-id",
	"from":"from-WhatsApp-phone",
	"to":"to-WhatsApp-phone",
	"type":"alert",
	"timestamp":"timestamp-for-WhatsApp-message",
	"status":"WhatsApp-message-status",
	"error":"WhatsApp-error-message"
}
Parameters:

Parameter name

Data type

Description

Possible values

ID

String

WhatsApp message ID

"ABGHVJNHZYFRPwIQtAkyZ4zvbaRCCwqa1ekDuQ"

from
String
The issuer's WhatsApp number in international format.
"0019875632588"
to
String
The receiver's WhatsApp number.
"0034675572588"
type
String
Type of request. "alert" is the only possible value.
"alert"
timestamp
Number
Time when the alert was received. Timestamp is in seconds.
"1593554400"
status
String
WhatsApp message status. It indicates status from WhatsApp message.
Check status types in the next point
error
string
Reason for the error indicated by WhatsApp.
https://developers.facebook.com/docs/whatsapp/api/errors

Status types

  • "sent": the server received the message your company sent.

  • "delivered": the message your company sent was sent to the user's device.

  • "read": the user read the message your company sent. Read notifications are only available to users who have read receipt enabled. For users who do not have it enabled, you will only receive the delivery notification.

  • "failed": the message your company sent could not be sent.


Images

When a client sends you an image, the Woztell Client API will send an HTTP POST request notification to the Webhook URL in the following format:
{
        "id":"WhatsApp-message-id",
	"from":"from-WhatsApp-phone",
	"to":"to-WhatsApp-phone",
	"type":"image",
	"timestamp":"timestamp-for-WhatsApp-message",
	"base64":"base64-image-encode",
            "mimeType":"mimeType-image",
            "caption":"image-comment"
}            


Parameters:


Parameter name

Data type

Description

Possible Values

ID

String

WhatsApp Message ID

"ABGHVJNHZYFRPwIQtAkyZ4zvbaRCCwqa1ekDuQ"

from

String

Sender's WhatsApp number in international format

"0019875632588"

to

String

The recipient's WhatsApp number

"0034675572588"

type

String

Type of message. "image" is the only possible value.

"image"

timestamp

Number

Time the message was sent. The time stamp is in seconds

"1593554400"

base64

String

Base64 image encoding

"......................"

mimeType

String

Image format. Possible values: "image/png" or "image/jpeg"

"image/png"

caption

String

Commentary accompanying the image.

"Esto es un comentario"

​