Overview

Agents

API keys

Assistants (AI)

Automated messages

Blacklist

Channels

Comments

Companies

Contacts

Conversations

Labels

Lists

Messages

Notes

Profile

Teams

Templates

Webhooks

Get started

The Spotler Message API is a JSON REST API to connect to social messaging platforms like WhatsApp Business, Apple Messages for Business, Facebook Messenger, Twitter DM, Viber, LINE and more.

HTTP requests

Standard HTTP methods like GET and POST are used with the application/json content type. API keys are used for authentication and TLS 1.2 is required.

HTTP responses

HTTP status codes like 200 OK and 201 Created are returned for successful responses and the response data has the application/json content type.

Error messages

HTTP status codes like 400 Bad Request and 401 Unauthorized are returned for error responses. See error codes for more information.

Channels & JIDs

Spotler Message uses Jabber IDs (JIDs) to represent channels and contacts. They have the same format as an e-mail address. The following channels are supported:

Channel Example JID
WhatsApp Business 31611111111@whatsapp.eazy.im
Instagram DM 1918363544518991@instagram.eazy.im
Google's Business Messages 964468cf-a3fd-4f0a-ad44-bcd7c7e5a424@gbm.eazy.im
Apple Messages for Business d2b9f484-08ac-45a7-bbe0-f2f7d844bcb6@apple.eazy.im
Facebook Messenger 1918363544518991@messenger.eazy.im
Twitter DM 872362551@twitter.eazy.im
Web chat 8191584934115639@webchat.eazy.im
SMS 31633333333@sms.eazy.im

Tip: Custom channels can be added per customer. For instance, an existing chat in the customer's mobile app or live chat on the website can be added as channel in Spotler Message.

Error codes

HTTP status codes like 400 Bad Request and 401 Unauthorized are returned for error responses. The JSON error response structure is as follows: 

            400 Bad Request

{
    "error": {
        "code": 1005,
        "message": "Jid is invalid"
    },
    "traceId": "7e6459"
}

The traceId can be used by our support team to track down the corresponding request.

The following error codes are defined:

Error code Description
1001 Unauthorized
1002 Access denied
1003 Service unavailable
1004 Internal server error
1005 Validation error
1006 Template name does not exist
1007 User does not have WhatsApp
1008 Media is invalid
1009 Not found
1010 Assistant has no ownership of conversation
1011 Message rejected
1012 Bad gateway
1013 Parameter count mismatch
1014 Already exists
1015 Customer care window expired

Migration from v2

Customers who already use API v2 are requested migrate to v3. New API v3 keys will be provided so live implementations will not be impacted until fully migrated.

Most important changes

Important: API v2 is currently deprecated and no new features will be added. Customers are strongly advised to migrate to v3.

Contact us

Have questions? Contact our support at https://wa.me/31302106499 or via support@eazy.im

Read agents

A list of all agents can be retrieved using the GET method. 

             assistantGET https://api.eazy.im/v3/companies/{companyId}/agents
        
            200 OK

[
    {
        "email": "jane@mycompany.com",
        "jid": "489cc9a6-c0da-4930-825e-036b23b5a2f2@agent.eazy.im",
        "name": [
            "firstName": "Jane",
            "fullName": "Jane Myers",
            "lastName": "Myers"
        ],
        "roles": [
            "admin",
            "user"
        ],
        "status": "OFFLINE",
        "teams": ["123456789000@team.eazy.im"]
    },
    {
        "email": "mike@mycompany.com",
        "jid": "f431a0cb-3517-4eaa-9154-7ad2fc3cc2e0@agent.eazy.im",
        "name": [
            "firstName": "Mike",
            "fullName": "Mike Doohan",
            "lastName": "Doohan"
        ],
        "roles": [
            "user"
        ],
        "status": "AWAY",
        "teams": ["123456789000@team.eazy.im"]
    },
    {
        "email": "wesley@mycompany.com",
        "jid": "615b4043-5126-4af8-9128-2321fceb7358@agent.eazy.im",
        "name": [
            "firstName": "Wesley",
            "fullName": "Wesley Crusher",
            "lastName": "Crusher"
        ],
        "roles": [
            "user"
        ],
        "status": "ONLINE",
        "teams": ["123456789000@team.eazy.im"]
    }
]

A specific agent can be requested as follows:

             assistantGET https://api.eazy.im/v3/companies/{companyId}/agents/{email}
        
            200 OK

{
    "email": "wesley@mycompany.com",
    "jid": "615b4043-5126-4af8-9128-2321fceb7358@agent.eazy.im",
    "name": [
        "firstName": "Wesley",
        "fullName": "Wesley Crusher",
        "lastName": "Crusher"
    ],
    "roles": [
        "user"
    ],
    "status": "ONLINE",
    "teams": ["123456789000@team.eazy.im"]
}

Assistants

Assistants can be used to automate conversations.

Read assistants

A list of all assistants can be requested using the GET method.

             assistantGET https://api.eazy.im/v3/companies/{companyId}/assistants
        
            200 OK

[
    {
        "color": 8,
        "description": "Sales assistant",
        "enabled": true,
        "jid": "1563451622477@ai.eazy.im",
        "name": "Sales"
    },
    {
        "color": 16,
        "description": "Support assistant",
        "enabled": true,
        "jid": "1580486135318@ai.eazy.im",
        "name": "Support"
    }
]

Update an assistant

An assistant can be updated using the PATCH method. Only the specified fields will be updated, all other fields will remain unchanged.

The following fields can be updated: color, description, enabled, name 

             assistantPATCH https://api.eazy.im/v3/companies/{companyId}/assistants/{jid}

{
    "description": "Sales assistant"
}
        
            200 OK

{
    "color": 8,
    "description": "Sales assistant",
    "enabled": true,
    "jid": "1563451622477@ai.eazy.im",
    "name": "Sales"
}

Read automated messages

A list of all automated messages can be requested using the GET method.

            channelGET https://api.eazy.im/v3/channels/{channelJid}/automated-messages
        
            200 OK

[
    {
        "body": "Sorry, we are currently closed. Your question will be answered as soon as possible.",
        "createdAt": "2020-03-11T19:00:02.000000Z",
        "enabled": true,
        "type": "AWAY",
        "updatedAt": null
    },
    {
        "body": "Welcome to My Company 😎 We are here to help 💪",
        "createdAt": "2020-04-29T11:37:40.000000Z",
        "enabled": false,
        "type": "GREETING",
        "updatedAt": null
    }
]

A specific automated message can be requested as follows:

            channelGET https://api.eazy.im/v3/channels/{channelJid}/automated-messages/{type}
        
            200 OK

{
    "body": "Welcome to My Company 😎 We are here to help 💪",
    "createdAt": "2020-04-29T11:37:40.000000Z",
    "enabled": false,
    "type": "GREETING",
    "updatedAt": null
}

Update automated message

An automated message can be updated using the PATCH method. Only the specified fields will be updated, all other fields will remain unchanged.

The following fields can be updated: body, enabled 

            channelPATCH https://api.eazy.im/v3/channels/{channelJid}/automated-messages/{type}

{
    "enabled": false
}
        
            200 OK

{
    "body": "Sorry, we are currently closed. Your question will be answered as soon as possible.",
    "createdAt": "2020-03-11T19:00:02.000000Z",
    "enabled": false,
    "type": "AWAY",
    "updatedAt": "2020-04-29T15:22:07.000000Z"
}

Block a contact

A contact can be blocked by adding it to the blacklist. Messages received from a blocked contact will be ignored and it is not possible to send messages to it. 

            channelPOST https://api.eazy.im/v3/channels/{channelJid}/contacts/blacklist/{contactJid}
        
            204 No Content

Read blacklist

A list of all blocked contacts can be requested using the GET method.

            channelGET https://api.eazy.im/v3/channels/{channelJid}/contacts/blacklist
        
            200 OK

[
    "31611112222@whatsapp.eazy.im",
    "31622223333@whatsapp.eazy.im",
    "31644445555@whatsapp.eazy.im"
]

Unblock a contact

A contact can be removed from the blacklist using the DELETE method.

            channelDELETE https://api.eazy.im/v3/channels/{channelJid}/contacts/blacklist/{contactJid}
        
            204 No Content

API keys

The Spotler Message API uses API keys for authentication. The API key is transmitted using the Authentication header with the Bearer scheme:

            Authorization: Bearer Tnhip5Hiq10gGiKhNS850ShCAjIQZAgKDAN0JAIL

Scopes

Each key has a scope which defines to which endpoints the key has access to. The following scopes are defined:

Scope Description
channel Access to channel related endpoints
assistant Same as channel including assistant related endpoints
company Same as channel including company related endpoints
owner Same as company including owner related endpoints

Read API keys

A list of all keys can be retrieved using the GET method. The objects field specifies to which objects the key has access to. IP whitelisting can be used to restrict originating IP addresses.

Note: API keys are stored in a hashed format so it is not possible to retrieve them. 

             companyGET https://api.eazy.im/v3/keys
        
            200 OK

[
    {
        "cipherKey": null,
        "description": null,
        "id": "509000e9-05c9-43a9-b6f1-70f1c6a5448a",
        "lastUsed": "2020-03-11T19:53:02.000000Z",
        "objects": [
            {
                "jid": "31612345678@whatsapp.eazy.im",
                "type": "CHANNEL"
            }
        ],
        "scope": "CHANNEL",
        "whitelist": null
    }
]

The current API key can be requested as follows:

            channelGET https://api.eazy.im/v3/keys/current
        
            200 OK

{
    "cipherKey": null,
    "description": "Test environment",
    "id": "509000e9-05c9-43a9-b6f1-70f1c6a5448a",
    "lastUsed": "2020-03-11T19:53:02.000000Z",
    "objects": [
        {
            "jid": "31612345678@whatsapp.eazy.im",
            "type": "CHANNEL"
        }
    ],
    "scope": "CHANNEL",
    "whitelist": [
        "95.101.207.62"
    ]
}

Channels

TODO

Read channels

A list of all channels can be requested using the GET method.

             channelGET https://api.eazy.im/v3/channels
        
            200 OK

[
    {
        "dataRetentionInDays": 90,
        "jid": "31611111111@whatsapp.eazy.im",
        "name": "WhatsApp",
        "priority": null
    },
    {
        "dataRetentionInDays": 90,
        "jid": "8194c1a3-be55-4210-ac02-58a992c17977@apple.eazy.im",
        "name": "Apple Messages for Business",
        "priority": null
    }
]

Update a channel

A channel can be updated using the PATCH method. Only the specified fields will be updated, all other fields will remain unchanged.

The following fields can be updated: name, priority 

             channelPATCH https://api.eazy.im/v3/channels/{channelJid}

{
    "name": "KLM.com"
}
        
            200 OK

{
    "dataRetentionInDays": 90,
    "jid": "31611111111@whatsapp.eazy.im",
    "name": "KLM.com",
    "priority": null
}

Create a comment

Create a new comment for a conversation.

            assistantPOST https://api.eazy.im/v3/channels/{channelJid}/conversations/{contactJid}/comments

{
    "body": "Order #51616 has been delivered"
}
        
            201 Created

{
    "id": "ee487689cac84dedcf972ff1d8d10ed7b64f4148"
}

Companies

Each customer is defined by a company. Customers can only manage their own company except for resellers who can manage multiple companies.

Read companies

The current company can be requested as follows:

            channelGET https://api.eazy.im/v3/companies/current
        
            200 OK

{
    "id": "458e633a-ab50-445f-9d1f-52afbf720ec3",
    "name": "KLM"
}

A list of all companies can be retrieved using the GET method. 

             channelGET https://api.eazy.im/v3/companies
        
            200 OK

[
    {
        "id": "458e633a-ab50-445f-9d1f-52afbf720ec3",
        "name": "KLM"
    },
    {
        "id": "a0762e91-7d0d-4785-be49-d77516cb00c4",
        "name": "Air France"
    }
]

A specific company can be requested as follows:

            channelGET https://api.eazy.im/v3/companies/{id}
        
            200 OK

{
    "id": "458e633a-ab50-445f-9d1f-52afbf720ec3",
    "name": "KLM"
}

Create a contact

Create a new contact.

            channelPOST https://api.eazy.im/v3/channels/{channelJid}/contacts

{
    "jid": "31611111111@whatsapp.eazy.im",
    "name": "John Doe",
    "reference": "Customer #545",
    "remarks": "VIP"
}
        
            201 Created

{
    "metadata": [],
    "name": [
        "firstName": "John",
        "fullName": "John Doe",
        "lastName": "Doe"
    ],
    "notes": [],
    "phoneNumber": 31611111111,
    "reference": "Customer #545",
    "remarks": "VIP",
    "type": "INDIVIDUAL"
}

Read contact

A contact can be retrieved using the GET method.

            channelGET https://api.eazy.im/v3/channels/{channelJid}/contacts/{contactJid}
        
            200 OK

{
    "metadata": [],
    "name": [
        "firstName": "John",
        "fullName": "John Doe",
        "lastName": "Doe"
    ],
    "notes": [
        {
            "body": "Return order received",
            "createdAt": "2020-03-11T19:53:02.000000Z",
            "createdBy": "john@mycompany.com",
            "id": "280cbbe0-c08a-4606-bf8d-a30242c4eaa4",
            "isReadOnly": false,
            "updatedAt": null,
            "referenceId": null
        }
    ],
    "phoneNumber": 31611111111,
    "reference": "Customer #545",
    "remarks": "VIP",
    "type": "INDIVIDUAL"
}

Update a contact

A contact can be updated using the PATCH method. Only the specified fields will be updated, all other fields will remain unchanged.

The following fields can be updated: metadata, name, reference, remarks 

             channelPATCH https://api.eazy.im/v3/channels/{channelJid}/contacts/{contactJid}

{
    "metadata": [
        "title": "Mr."
    ],
    "name": "John Doe"
}
        
            200 OK

{
    "metadata": [
        "title": "Mr."
    ],
    "name": [
        "firstName": "John",
        "fullName": "John Doe",
        "lastName": "Doe"
    ],
    "notes": [],
    "phoneNumber": 31611111111,
    "reference": "Customer #545",
    "remarks": "VIP",
    "type": "INDIVIDUAL"
}

Delete a contact

An existing contact including all its messages and all other data belonging to the contact can be deleted by using the DELETE method.

            channelDELETE https://api.eazy.im/v3/channels/{channelJid}/contacts/{contactJid}
        
            204 No Content

Read conversation

A conversation can be requested using the GET method.

             assistantGET https://api.eazy.im/v3/channels/{channelJid}/conversations/{contactJid}
        
            200 OK

{
    "assignee": "john@mycompany.com",
    "channel": {
        "jid": "31612345678@whatsapp.eazy.im"
    },
    "contact": {
        "jid": "31611111111@whatsapp.eazy.im"
    },
    "createdAt": "2019-04-04T15:29:47.000000Z",
    "id": "swe9lhoGn5mMWBXNSm/BMO6/JEA=",
    "labels": [],
    "lastMessageReceivedAt": "2019-04-08T23:55:39.000000Z",
    "lastMessageSentAt": "2019-04-07T17:12:00.000000Z",
    "messagesReceived": 12,
    "messagesSent": 8,
    "status": "OPEN",
    "unreadCount": null
}

Update a conversation

A conversation can be updated using the PATCH method. Only the specified fields will be updated, all other fields will remain unchanged.

The following fields can be updated: assignee, labels, status, team, unreadCount 

             assistantPATCH https://api.eazy.im/v3/channels/{channelJid}/conversations/{contactJid}

{
    "status": "CLOSED"
}
        
            200 OK

{
    "assignee": "john@mycompany.com",
    "channel": {
        "jid": "31612345678@whatsapp.eazy.im"
    },
    "contact": {
        "jid": "31611111111@whatsapp.eazy.im"
    },
    "createdAt": "2019-04-04T15:29:47.000000Z",
    "labels": [],
    "lastMessageReceivedAt": "2019-04-08T23:55:39.000000Z",
    "lastMessageSentAt": "2019-04-07T17:12:00.000000Z",
    "messagesReceived": 12,
    "messagesSent": 8,
    "status": "CLOSED",
    "team": {
        "jid": "1601626130348@team.eazy.im"
    },
    "unreadCount": null
}

Use cases

The following table shows the most common use cases for quick reference.

Example Description
status: "CLOSED" Close the conversation
assignee: "john@mycompany.com" Handover the conversation from the assistant to a specific agent or assistant
assignee: null Handover the conversation from the assistant to the agents
labels: ["1580486175684@label.eazy.im"] Label the conversation with the specified labels
labels: [] Unlabel the conversation
unreadCount: null Mark as read
unreadCount: 0 Mark as unread

Create a label

Create a new label. The name must be unique.

            assistantPOST https://api.eazy.im/v3/companies/{companyId}/labels

{
    "description": "Support related questions",
    "name": "Support"
}
        
            201 Created

{
    "color": 8,
    "jid": "1580486135318@label.eazy.im",
    "name": "Support",
    "priority: null
}

Read labels

A list of all labels can be requested using the GET method.

             assistantGET https://api.eazy.im/v3/companies/{companyId}/labels
        
            200 OK

[
    {
        "color": 16,
        "jid": "1563451622477@label.eazy.im",
        "name": "Sales",
        "priority: null
    },
    {
        "color": 8,
        "jid": "1580486135318@label.eazy.im",
        "name": "Support",
        "priority: null
    }
]

Update a label

A label can be updated using the PATCH method. Only the specified fields will be updated, all other fields will remain unchanged.

The following fields can be updated: color, name, priority 

             assistantPATCH https://api.eazy.im/v3/companies/{companyId}/labels/{jid}

{
    "name": "Customer Support"
}
        
            200 OK

{
    "color": 8,
    "jid": "1580486135318@label.eazy.im",
    "name": "Customer Support",
    "priority: null
}

Delete a label

An existing label can be deleted by using the DELETE method.

            assistantDELETE https://api.eazy.im/v3/companies/{companyId}/labels/{jid}
        
            204 No Content

Read lists

All lists can be requested using the GET method.

             channelGET https://api.eazy.im/v3/channels/{channelJid}/lists
        
            200 OK

[
    {
        "jid": "1571833730@list.eazy.im",
        "metadata": [],
        "name": {
            "fullName": "Mailing list"
        },
        "notes": [],
        "reference": null,
        "remarks": null,
        "type": "LIST"
    },
    {
        "jid": "1571833731@list.eazy.im",
        "metadata": [],
        "name": {
            "fullName": "Sales",
        },
        "notes": [],
        "reference": null,
        "remarks": null,
        "type": "LIST"
    }
]

Create a list

Create a new list

            channelPOST https://api.eazy.im/v3/channels/{channelId}/lists

{
    "name": "Marketing campaign"
}
        
            201 Created

{
    "contacts": [],
    "jid": "1644929310@list.eazy.im",
    "metadata": [],
    "name": {
        "fullName": "Marketing campaign"
    },
    "notes": [],
    "reference": null,
    "remarks": null,
    "type": "LIST"
}

Add contact to a list

A contact can be added to a list using the POST method.

             channelPOST https://api.eazy.im/v3/channels/{channelJid}/lists/{listJid}/participants/{contactJid}
        
            200 OK

[]

Remove contact from a list

A contact can be removed from a list using the DELETE method.

             channelDELETE https://api.eazy.im/v3/channels/{channelJid}/lists/{listJid}/participants/{contactJid}
        
            200 OK

[]

Messages

The JSON structure of each message type is listed below.

Audio

Element Value Mandatory Description
mimeType string Y MIME type
type "audio" Y Message type

Contact

Element Value Mandatory Description
contacts array Y Contact structure
type "contact" Y Message type

Document

Element Value Mandatory Description
fileName string Y File name
mimeType string Y MIME type
title string Y Document title
type "document" Y Message type

Gif

Element Value Mandatory Description
caption string N Caption text message
mimeType string Y MIME type
type "gif" Y Message type

Image

Element Value Mandatory Description
caption string N Caption text message
mimeType string Y MIME type
type "image" Y Message type

Location

Element Value Mandatory Description
latitude float Y Latitude coordinate
longitude float Y Longitude coordinate
name string N Name of the location
type "location" Y Message type
url string N Website URL

Voice message

Element Value Mandatory Description
mimeType string Y MIME type
type "ptt" Y Message type

Sticker

Element Value Mandatory Description
mimeType string Y MIME type
type "sticker" Y Message type

Template

Element Value Mandatory Description
template array Y Template structure
type "template" Y Message type

Text

Element Value Mandatory Description
body string Y Message body
type "text" Y Message type

Video

Element Value Mandatory Description
caption string N Caption text message
mimeType string Y MIME type
type "video" Y Message type

Send messages

A message can be send using the POST method.

             channelPOST https://api.eazy.im/v3/channels/{channelJid}/messages/{contactJid}

{
    "message": {
        "body": "Have a nice day!",
        "type": "text"
    }
}
        
            201 Created

{
    "id": "b48eaa2fab1e942cdec8b8717ec6bf3ed2dad05a"
}

The returned id can be used to match delivery receipts to the original message.

WhatsApp examples

Button message

{
    "message": {
        "interactive": {
            "components": {
                "body": {
                    "text": "How can we help you?",
                    "type": "text"
                },
                "buttons": [
                    {
                        "reply": {
                            "payload": "button_id_1",
                            "title": "Option 1"
                        },
                        "type": "reply"
                    },
                    {
                        "reply": {
                            "payload": "button_id_2",
                            "title": "Option 2"
                        },
                        "type": "reply"
                    }
                ]
            },
            "type": "button"
        },
        "type": "interactive"
    }
}

List message

{
    "message": {
        "interactive": {
            "components": {
                "body": {
                    "text": "How can we help you?",
                    "type": "text"
                },
                "list": {
                    "title": "Make a choice",
                    "sections": [
                        {
                            "rows": [
                                {
                                    "description": "Optional description",
                                    "payload": "button_id_1",
                                    "title": "Option 2"
                                },
                                {
                                    "description": "Optional description",
                                    "payload": "button_id_2",
                                    "title": "Option 2"
                                },
                                {
                                    "description": "Optional description",
                                    "payload": "button_id_3",
                                    "title": "Option 3"
                                }
                            ],
                            "title": "Section 1"
                        }
                    ]
                }
            },
            "type": "list"
        },
        "type": "interactive"
    }
}

Single product message

{
    "message": {
        "interactive": {
            "components": {
                "body": {
                    "text": "Here is a suggested product for you",
                    "type": "text"
                },
                "product": {
                    "productId": "1105524"
                }
            },
            "type": "product"
        },
        "type": "interactive"
    }
}

Multi product message

{
    "message": {
        "interactive": {
            "components": {
                "header": {
                    "text": "Make a selection",
                    "type": "text"
                },
                "body": {
                    "text": "Here are some suggested products for you",
                    "type": "text"
                },
                "productList": {
                    "sections": [
                        {
                            "items": [
                                {
                                    "productId": "1105521"
                                },
                                {
                                    "productId": "1105522"
                                },
                                {
                                    "productId": "1105523"
                                }
                            ],
                            "title": "Our Collection"
                        }
                    ]
                }
            },
            "type": "productList"
        },
        "type": "interactive"
    }
}

Create a note

Create a new note for a contact.

            assistantPOST https://api.eazy.im/v3/channels/{channelJid}/contacts/{contactJid}/notes

{
    "body": "Customer number #63553",
    "referenceId": "CUSTOMER_NUMBER"
}
        
            201 Created

{
    "body": "Customer number #63553",
    "createdAt": "2020-03-11T19:00:02.000000Z",
    "createdBy": "1558982559179@ai.eazy.im",
    "id": "edff51c3-4d8c-4d06-bd48-d61e993ecc57",
    "isPinned": false,
    "isReadOnly": false,
    "updatedAt": null,
    "referenceId": "CUSTOMER_NUMBER"
}

Read notes

A list of all notes from a contact can be requested using the GET method.

            assistantGET https://api.eazy.im/v3/channels/{channelJid}/contacts/{contactJid}/notes
        
            200 OK

[
    {
        "body": "Important customer",
        "createdAt": "2020-03-11T19:00:02.000000Z",
        "createdBy": "john@mycompany.com",
        "id": "e26a5285-f516-4ae3-8ac4-ba06da8ac946",
        "isPinned": false,
        "isReadOnly": false,
        "updatedAt": null,
        "referenceId": null
    },
    {
        "body": "Customer number #63553",
        "createdAt": "2020-03-11T19:00:02.000000Z",
        "createdBy": "1558982559179@ai.eazy.im",
        "id": "edff51c3-4d8c-4d06-bd48-d61e993ecc57",
        "isPinned": false,
        "isReadOnly": false,
        "updatedAt": null,
        "referenceId": "CUSTOMER_NUMBER"
    }
]

Update a note

A note can be updated using the PATCH method. Only the specified fields will be updated, all other fields will remain unchanged.

The following fields can be updated: body, isPinned, isReadOnly, referenceId 

            assistantPATCH https://api.eazy.im/v3/channels/{channelJid}/contacts/{contactJid}/notes/{id}

{
    "body": "Customer number #63554",
    "isPinned": true
}
        
            200 OK

{
    "body": "Customer number #63554",
    "createdAt": "2020-03-11T19:00:02.000000Z",
    "createdBy": "1558982559179@ai.eazy.im",
    "id": "edff51c3-4d8c-4d06-bd48-d61e993ecc57",
    "isPinned": true,
    "isReadOnly": false,
    "updatedAt": "2020-03-11T19:17:58.000000Z",
    "referenceId": "CUSTOMER_NUMBER"
}

Delete a note

An existing note can be deleted by using the DELETE method.

            assistantDELETE https://api.eazy.im/v3/channels/{channelJid}/contacts/{contactJid}/notes/{id}
        
            204 No Content

WhatsApp Business profile

WhatsApp Business accounts have a profile which consists of a logo, business information and an about message.

Read profile

The WhatsApp Business profile can be retrieved using the GET method.

            channelGET https://api.eazy.im/v3/channels/{channelJid}/profile
        
            200 OK

{
    "about": "Welcome! We are here to help you 24/7",
    "businessProfile": {
        "address": "High Street 15, New York",
        "description": "Your Company",
        "email": "info@your-company.com",
        "vertical": null,
        "websites": [
            "https://your-company.com"
        ]
    },
    "name": "My Company",
    "phoneNumber": 31612345678,
    "pictureUrl": "https://pps.whatsapp.net/v/t61.24694-24/s96x96/71527172_751740171986704_2078049712831220364_n.jpg?oe=5E2168E9&oh=174efd2076218dff633a1e748beac190"
}

Update profile

The WhatsApp Business profile can be completely overwritten or partially updated.

The POST method is used to overwrite the whole profile. 

            channelPOST https://api.eazy.im/v3/channels/{channelJid}/profile

{
    "about": "Welcome! We are here to help you 24/7",
    "businessProfile": {
        "address": "High Street 15, New York",
        "description": "Your Company",
        "email": "info@your-company.com",
        "vertical": null,
        "websites": [
            "https://your-company.com"
        ]
    }
}
        
            200 OK

{
    "about": "Welcome! We are here to help you 24/7",
    "businessProfile": {
        "address": "High Street 15, New York",
        "description": "Your Company",
        "email": "info@your-company.com",
        "vertical": null,
        "websites": [
            "https://your-company.com"
        ]
    }
}

The PATCH method is used for a partial update. Unspecified fields will remain unchanged.

            channelPATCH https://api.eazy.im/v3/channels/{channelJid}/profile

{
    "businessProfile": {
        "email": "support@your-company.com"
    }
}
        
            200 OK

{
    "about": "Welcome! We are here to help you 24/7",
    "businessProfile": {
        "address": "High Street 15, New York",
        "description": "Your Company",
        "email": "support@your-company.com",
        "vertical": null,
        "websites": [
            "https://your-company.com"
        ]
    }
}

Create a team

Create a new team

            assistantPOST https://api.eazy.im/v3/companies/{companyId}/teams

{
    "name": "Support"
}
        
            201 Created

{
    "channels": [],
    "color": 8,
    "jid": "1580486135318@team.eazy.im",
    "metadata": null,
    "name": "Support"
}

Read teams

A list of all teams can be requested using the GET method.

             assistantGET https://api.eazy.im/v3/companies/{companyId}/teams
        
            200 OK

[
    {
        "channels": [],
        "color": 1,
        "jid": "1580486137310@team.eazy.im",
        "metadata": null,
        "name": "Sales",
        "reference": null
    },
    {
        "channels": [],
        "color": 8,
        "jid": "1580486135318@team.eazy.im",
        "metadata": null,
        "name": "Support",
        "reference": null
    }
]

Update a team

A team can be updated using the PATCH method. Only the specified fields will be updated, all other fields will remain unchanged.

The following fields can be updated: color, metadata, name, reference 

             assistantPATCH https://api.eazy.im/v3/companies/{companyId}/teams/{jid}

{
    "name": "Customer Support"
}
        
            200 OK

{
    "channels": [],
    "color": 8,
    "jid": "1580486135318@team.eazy.im",
    "metadata": null,
    "name": "Customer Support",
    "reference": null
}

Delete a team

An existing team can be deleted by using the DELETE method.

            assistantDELETE https://api.eazy.im/v3/companies/{companyId}/teams/{jid}
        
            204 No Content

Create a template

Create a new WhatsApp Business template. Templates can include a header, body, footer and buttons.

            channelPOST https://api.eazy.im/v3/channels/{channelJid}/templates

{
    "category": "TRANSACTIONAL",
    "components": [
        {
            "text": "Hello {{1}}, how can I help you?",
            "type": "BODY"
        }
    ],
    "language": "en",
    "name": "support_after_24hours"
}
        
            201 Created

An example of a media template with a header, body, footer and buttons is as follows:

{
    "category": "TRANSACTIONAL",
    "components": [
        {
            "format": "DOCUMENT",
            "type": "HEADER"
        },
        {
            "text": "This is your KLM ticket for your flight on December 20th to New York.",
            "type": "BODY"
        },
        {
            "text": "Questions? We are available now, just send us a message",
            "type": "FOOTER"
        },
        {
            "buttons": [
                {
                    "text": "Confirm",
                    "type": "QUICK_REPLY"
                },
                {
                    "text": "Reschedule",
                    "type": "QUICK_REPLY"
                }
            ],
            "type": "BUTTONS"
        }
    ],
    "language": "en",
    "name": "ticket"
}

Read templates

All WhatsApp Business templates can be retrieved using the GET method.

            channelGET https://api.eazy.im/v3/channels/{channelJid}/templates
        
            200 OK

{
    "namespace": "e08e69cb_d136_86fc_c33f_0f64becd1f46",
    "templates": [
        {
            "category": "TRANSACTIONAL",
            "name": "delivery_notification",
            "translations": [
                {
                    "components": [
                        {
                            "text": "Hello {{1}}, your order with reference {{2}} has been delivered.",
                            "type": "BODY"
                        }
                    ],
                    "localeName": "en",
                    "status": "APPROVED"
                },
                {
                    "components": [
                        {
                            "text": "Hallo {{1}}, je bestelling met nummer {{2}} is afgeleverd.",
                            "type": "BODY"
                        }
                    ],
                    "localeName": "nl",
                    "rejectedReason": "NONE",
                    "status": "APPROVED"
                }
            ]
        },
        {
            "category": "TRANSACTIONAL",
            "name": "hello",
            "translations": [
                {
                    "components": [
                        {
                            "text": "Hello {{1}}",
                            "type": "BODY"
                        }
                    ],
                    "localeName": "en",
                    "rejectedReason": "PROMOTIONAL",
                    "status": "REJECTED"
                }
            ]
        }
    ]
}

Delete a template

An existing template can be deleted by using the DELETE method.

            assistantDELETE https://api.eazy.im/v3/channels/{channelJid}/templates/{name}
        
            204 No Content

Webhooks

Webhooks are used to receive real-time events like messages and receipts. Multiple webhooks can be defined per channel, each with their own events.

Webhooks must always return a 200 OK response. In case of connection or HTTP errors the platform will retry indefinitely.

Note: HTTPS with TLS 1.2 is required. Self signed certificates are not allowed.

Events

The following events are defined:

Name Description
custom Custom event for specific customer purposes
echo Outgoing messages sent by agents or assistants
handover Handover event whenever a conversation is transferred to an assistant or agent
label Label event whenever a conversation is labelled or unlabelled
message Incoming messages from customers
note Note creation or deletion event
postback Postback event for WhatsApp button templates, Apple list pickers etc
receipt Message receipt event
template_pack Template updates whenever templates are approved, rejected etc.
typing Typing indications when customers are typing a message

Create a webhook

Create a new webhook for the specified events.

            channelPOST https://api.eazy.im/v3/channels/{channelJid}/webhooks

{
    "events": [
        "message"
    ],
    "url": "https://your.company.com/webhook"
}
        
            201 Created

{
    "assistant": null,
    "cipherKey": null,
    "createdAt": "2020-03-11T19:00:02.000000Z",
    "enabled": true,
    "events": [
        "message"
    ],
    "headers": null,
    "id": "8520d8d6-7b28-4d6f-8631-ecd528a0246d",
    "updatedAt": null,
    "url": "https://your.company.com/webhook"
}

Read webhooks

All configured webhooks can be retrieved using the GET method.

            channelGET https://api.eazy.im/v3/channels/{channelJid}/webhooks
        
            200 OK

[
    {
        "assistant": null,
        "cipherKey": null,
        "createdAt": "2020-03-11T19:00:02.000000Z",
        "enabled": true,
        "events": [
            "message"
        ],
        "headers": null,
        "id": "8520d8d6-7b28-4d6f-8631-ecd528a0246d",
        "updatedAt": null,
        "url": "https://your.company.com/webhook"
    },
    {
        "assistant": null,
        "cipherKey": null,
        "createdAt": "2020-03-11T19:01:02.000000Z",
        "enabled": true,
        "events": [
            "receipt"
        ],
        "headers": {
            "Authorization": "Bearer SomeApiKey"
        },
        "id": "3cd6cfb7-ca45-44fe-a01e-8aba4332b366",
        "updatedAt": null,
        "url": "https://your.company.com/webhook-receipt"
    }
]

Update a webhook

A webhook can be updated using the PATCH method. Only the specified fields will be updated, all other fields will remain unchanged.

The following fields can be updated: enabled, events, headers, url 

             channelPATCH https://api.eazy.im/v3/channels/{channelJid}/webhooks/{id}

{
    "url": "https://your.company.com/new-webhook"
}
        
            200 OK

{
    "assistant": null,
    "cipherKey": null,
    "createdAt": "2020-03-11T19:00:02.000000Z",
    "enabled": true,
    "events": [
        "message"
    ],
    "headers": null,
    "id": "8520d8d6-7b28-4d6f-8631-ecd528a0246d",
    "updatedAt": "2020-03-11T19:53:02.000000Z",
    "url": "https://your.company.com/new-webhook"
}

Delete a webhook

An existing webhook can be deleted by using the DELETE method.

            channelDELETE https://api.eazy.im/v3/channels/{channelJid}/webhooks/{id}
        
            204 No Content