Chat message operations

Introduction
Operations

Introduction

Once you have the token, you can start sending requests to the API.

Operations

Send message

You can send a message to a specific chat.

HTTP Request

POST /api/v1/private/chats/{chatId}/messages

With the following information provided as JSON. For a Telegram "Chat":

{
        "text": "This is the message",
        "pinMessage": false
    }

Or, for a WhatsApp "Chat":

{
        "phone": "+34600000000",
        "text": "This is the message"
    }

Request body parameters

Parameter	Mandatory	Datatype	Description
text	yes	string	The message that is going to be sent to the chat
parseMode	no	string	Formatting of the message text (Telegram only). Valid values: "markdown", "markdownv2" and "HTML".
pinMessage	no	bool	If the message is going to be pinned (Telegram only)
phone	yes (whatsapp)	string	The phone number of the WhatsApp recipient, in international format. Mandatory for WhatsApp chats.

As response, you will get

204 No Content

which means the message has been accepted and will be delivered asynchronously.

Send template message (WhatsApp)

You can send a pre-approved WhatsApp template message to a specific chat.

HTTP Request

POST /api/v1/private/chats/{chatId}/templates

With the following information provided as JSON:

{
        "phone": "+34600000000",
        "service": "whatsapp",
        "templateName": "EXAMPLE_TEMPLATE",
        "templateLanguageCode": "es",
        "parameters": ["First parameter", "Second parameter"]
    }

Request body parameters

Parameter	Mandatory	Datatype	Description
phone	yes	string	The phone number of the WhatsApp recipient, in international format.
service	yes	string	The provider of the "Chat". Currently only "whatsapp" supports template messages.
templateName	no	string	The name of the WhatsApp template to send. If omitted, the default template configured for your tenant is used.
templateLanguageCode	no	string	The language code of the template. If omitted, the default language configured for your tenant is used.
parameters	no	array	List of string values to fill the template placeholders, in order.

As response, you will get 201 Created with the following JSON body:

{
    "chatId": "9a983789-1709-4543-aa31-a02867680017",
    "parentProcessId": "b3b1f9dc-84d7-4a13-9f39-1c1c4c0a8f21"
}

The template message is delivered asynchronously: "parentProcessId" identifies the background process that completes the delivery. Other responses: 404 ("Chat" not found).

Message detail

To be able to obtain the detail of a message of a "Chat"

HTTP Request

GET /api/v1/private/chats/{chatId}/messages/{messageId}

As response, you will get the following JSON object:


         {
    "id": "b5f28635-e2af-4d66-a2ab-a46d2e321c45",
    "writtenBy": "6bc24509-8243-4e62-aeb3-e3202f12c4ce",
    "writtenAt": "2024-10-15T10:55:31.000Z",
    "deleted": false,
    "content": [
        {
            "value": {
                "text": "Welcome to the chat! Everything that happens in this chat is being certified. By joining it, you are accepting our terms and conditions: https://example.com/terms. And you have read this privacy policy: https://example.com/privacy",
                "entities": [
                    {
                        "offset": 137,
                        "length": 25,
                        "type": "TextEntityTypeUrl"
                    },
                    {
                        "offset": 203,
                        "length": 27,
                        "type": "TextEntityTypeUrl"
                    }
                ]
            },
            "contentType": "application/x.chat-manager.message-text-formatted+json",
            "capturedAt": "2024-10-15T10:55:31.000Z",
            "evidenceId": "56bb335e-5e74-4493-a593-c8cb977c3b58",
            "hash": "e611c3b9a4015216956e62405b82224830664ba7c68069a8035874bf04bc8fd0"
        }
    ]
}

Where:

HTTP Response parameters

Parameter	Datatype	Description
id	UUID	An identification for the "Message". UUID V4
writtenBy	UUID	The user who writes the message
writtenAt	timestamp	The date the message was written
deleted	bool	If it is a deleted message.
content	object	An object with the information of the message
content.text	string	The text of the message
content.entities	array	The definition of a formated text.
content.contentType	contentType	The type of the message.
content.capturedAt	timestamp	The date and time of the message
content.evidenceId	uuid	The id of the evidence of the message (every message is an evidence)
content.hash	string	The hash of the evidence of the message (hexadecimal).

Message list

List of messages in a chat

HTTP Request

GET /api/v1/private/chats/{chatId}/messages

These calls can be paged. This is especially useful when you have to retrieve a big amount of elements.

By default, the size of the page is 20 elements, and you can put a maximum size of 200 elements. The response shows a list of resources to make the paged calls, basically you can set the page, the size, and the field you want to sort the list by.

These calls can be filtered. The filters are made by QueryParams:

Query parameters

Parameter	Mandatory	Datatype	Description
fromDate	no	timestamp	Return messages written from this date onwards.
toDate	no	timestamp	Return messages written up to this date.

As response, you will get the following JSON object:

{
    "records": [
        {
            "message": {
                "id": "b5f28635-e2af-4d66-a2ab-a46d2e321c45",
                "writtenBy": "6bc24509-8243-4e62-aeb3-e3202f12c4ce",
                "writtenAt": "2024-10-15T10:55:31.000Z",
                "deleted": false,
                "content": [
                    {
                        "value": {
                            "text": "Welcome to the chat! Everything that happens in this chat is being certified. By joining it, you are accepting our terms and conditions: https://example.com/terms. And you have read this privacy policy: https://example.com/privacy",
                            "entities": [
                                {
                                    "offset": 137,
                                    "length": 25,
                                    "type": "TextEntityTypeUrl"
                                },
                                {
                                    "offset": 203,
                                    "length": 27,
                                    "type": "TextEntityTypeUrl"
                                }
                            ]
                        },
                        "contentType": "application/x.chat-manager.message-text-formatted+json",
                        "capturedAt": "2024-10-15T10:55:31.000Z",
                        "evidenceId": "56bb335e-5e74-4493-a593-c8cb977c3b58"
                    }
                ]
            }
        }
    ],
    "_metadata": {
        "currentPage": 0,
        "totalPages": 12,
        "pageSize": 20,
        "totalRecords": 231
    }
}

Get attachment file

Some messages have attached files: image, video, audio, etc. This endpoint is used to obtain that file.

HTTP Request

GET /api/v1/private/chats/{chatId}/messages/{messageId}/attachment/file

As response, you will get 201 Created with a presigned URL in order to download the file:

{
    "url": "https://example.com/download/attachment.jpg",
    "expiration": "2024-06-17T15:10:00.000Z"
}

HTTP Response parameters

Parameter	Datatype	Description
url	string	The temporary download URL of the attached file.
expiration	timestamp	The expiration date and time of the download URL.

Message types

The types of messages that exist are:

application/x.chat-manager.message-deleted+json
application/x.chat-manager.message-text-formatted+json
application/x.chat-manager.message-location+json
application/x.chat-manager.message-poll+json
application/x.chat-manager.message-poll-status+json
application/x.chat-manager.message-poll-answer+json
application/x.chat-manager.chat-created+json
application/x.chat-manager.user-joined+json
application/x.chat-manager.user-removed+json
application/x.chat-manager.message-sticker+json
application/x.chat-manager.message-reaction+json
application/x-tgsticker
application/x.chat-manager.chat-icon+json
application/x.chat-manager.chat-icon-removed+json
application/x.chat-manager.chat-title+json
application/x.chat-manager.chat-description+json
application/x.chat-manager.message-pin+json
application/x.chat-manager.chat-enabled+json
application/x.chat-manager.chat-disabled+json