Saysimple API v3 (2023-09-01T12:53:21Z)

Every request needs both the Authorization and X-API-Key header to authorize the request.

If you like to work with Postman, you can download the API with the collection. Please be sure that the Authorization and X-API-Key are configured correctly.

Authorization

We recommend to setup the pre-request script as shown below at the root level of the collection, so every request can inherit the authorization from the parent. The script will also ensure that the X-API-Key will be added to every request.

pm.request.headers.add({
    key: "Authorization",
    value: pm.environment.get("Authorization")
});

pm.request.headers.add({
    key: "X-API-Key",
    value: pm.environment.get("X-API-Key")
});

Environment variables

Within Postman, you can setup an environment with it's own variables. When using the pre-request script as shown above, it's required to setup these environment variables.

The following channels are supported by the Saysimple API. Keep in mind the channels must be installed and configured before using them:

• Whatsapp Business
• Facebook Direct Message
• Twitter Direct Message
• Instagram Direct Message
• Webchat
• Google Business Messages
• Apple Business Chat
• Telegram Business Messaging
• SMS
• E-mail

Saysimple provides several webhooks to receive data when a specific event occurs. The data will be posted as a JSON object to a specified URL. Webhooks are versioned, when creating or updating a webhook you can pass along your desired version. In the table of available webhooks you can see which versions of each webhook are supported at this moment. Older versions may be deprecated and sunsetted eventually, so we encourage everyone to use the most recent versions. This document will show payloads for the newest versions available.

Available webhooks

Receive messages (via webhook)

It's possible to receive messages in real-time. Saysimple will forward incoming messages to a configured webhook if enabled. This is done with the POST method. The webhook endpoint needs to be configured to catch these POST requests.

The POST request includes a JSON body payload.

Example:

{
    "event": "entry::received",
    "payload": {
        "chat": {
            "id": 2,
            "contactId": 4,
            "channelId": 5,
            "platform": "whatsapp",
            "identity": "+31 6 xxxxxxxx",
            "assignedUserId": 6,
            "assignedTeamId": null,
            "status": "open",
            "externalReference": "xxxx8aaa2a4aac34aaae7a4e4xxxxxxx",
            "assignmentLastChangedAt": "2023-08-01T12:45:19.000Z",
            "createdAt": "2023-08-01T12:37:39.810Z",
            "chatTags": []
        },
        "entry": {
            "id": 3,
            "chatId": 2,
            "type": "message",
            "time": "2023-08-01T12:37:39.810Z",
            "direction": "in",
            "status": "received",
            "statusReason": null,
            "tags": null,
            "externalReference": null,
            "createdByEntity": "user",
            "createdById": 6,
            "createdAt": "2023-08-01T12:37:39.810Z",
            "message": "This is a dummy message!",
            "templateId": null,
            "components": null
        }
    },
    "module": "messaging",
    "webhookVersion": 3
}

Keep in mind that the URL of the attachments is available for 1 minute. After that period, the attachment won't be served.

Receive entry status updates (via webhooks)

When you like to receive data of a message when the status of the message changes, you can setup a webhook.
The webhook will be triggered when the message has been send, delivered, declined or read.

Example:

{
    "event": "entry::<x>",
    "status": "sent",
    "messageReference": "87d41c4ed6621f9cbcb63581d91a88d9",
    "payload": {
        "chat": {
            "id": 1,
            "contactId": 2,
            "channelId": 3,
            "platform": "test",
            "identity": "+31 6 xxxxxxxx",
            "assignedUserId": 6,
            "assignedTeamId": null,
            "status": "open",
            "externalReference": "xxxx8aaa2a4aac34aaae7a4e4xxxxxxx",
            "assignmentLastChangedAt": "2023-08-01T12:45:19.000Z",
            "createdAt": "2023-08-01T12:37:39.810Z",
            "chatTags": []
        },
        "entry": {
            "id": 1,
            "chatId": 5,
            "type": "message",
            "time": "2023-07-31T07:45:55.902Z",
            "direction": "out",
            "status": "sent",
            "statusReason": null,
            "tags": null,
            "externalReference": "87d41c4ed6621f9cbcb63581d91a88d9",
            "createdByEntity": "user",
            "createdById": 1,
            "createdAt": "2023-07-31T07:45:56.000Z",
            "metadata": {},
            "templateId": null,
            "message": "Test message",
            "components": null
        }
    },
    "module": "messaging",
    "webhookVersion": 3
}

Receive chat status updates (via webhooks)

Chats will have a status, for example if they’re new, assigned to an agent or archived. When the correct webhook has been set, you can receive the chat data when data has been changed, for example when the agent moves a chat to the archive or when the agent assigned a chat to someone else.

Example:

{
    "event": "chat::<x>",
    "payload": {
        "chat": {
            "id": 1,
            "contactId": 3,
            "channelId": 4,
            "platform": "whatsapp",
            "identity": "+31 6 xxxxxxxx",
            "assignedUserId": 2,
            "assignedTeamId": null,
            "status": "open",
            "assignmentLastChangedAt": "2023-07-31T08:05:12.000Z",
            "createdAt": "2023-07-31T07:55:34.000Z"
        },
        entry: null
    },
    "module": "messaging",
    "webhookVersion": 3
}

Our API is mainly used to send and receive messages. To send a message you must use the Messages - Create/Send endpoint:

https://api.saysimple.io/messaging/v3/messages/send

In the provided example, a template is used to demonstrate sending a message. If you don't want to send a template you can remove this section. Keep in mind that to start a chat, you must send a template first. Example:

{
    "contactActor": {
        "identity": "+31 6 xxxxxxxx",
    }
    "channelActor": {
        "channelId": "1",
    }
    "content": {
        "template": {
            "id": "1"
        },
        "text": "Hi, Welcome by Saysimple!",
    }
}

To retrieve all your available templates, you can use the Templates endpoint.

https://api.saysimple.io/messaging/v3/templates

To know more about templates please read the following knowledge base articles:
Template information and requesting new templates:
https://help.saysimple.com/request-a-whatsapp-template

Media Template information and requesting new media templates:
https://help.saysimple.com/whatsapp-media-templates

More information about the 24 hour customer care window:
https://help.saysimple.com/the-24-hour-customer-care-window

More information about conversation based pricing:
https://help.saysimple.com/whatsapp-conversation-based-pricing-1

We hope this documentation makes our API as clear as needed for your development process.
But we are happy to assist you in any way we can during development - up to certain extends of course 😉.
Please contact us at support@saysimple.com.