Chat operations

Introduction
Operations

Introduction

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

Operations

Register a "Chat"

The first interaction you have to do with the API is to create a "Chat".

HTTP Request

POST /api/v1/private/chats

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

{
        "service": "telegram",
        "title": "Title of the chat",
        "createdBy": "example created by",
        "description": "example description"
    }

Or, for a WhatsApp "Chat":

{
        "service": "whatsapp",
        "phone": "+34600000000",
        "createdBy": "example created by"
    }

Request body parameters

Parameter	Mandatory	Datatype	Description
service	no	string	The provider used to create the "Chat": "telegram" or "whatsapp". If omitted, the default service configured for your tenant is used.
chatId	no	UUID	Optional client-provided identifier for the new "Chat". UUID V4. If omitted, the system generates one.
title	yes (telegram)	string	A title for the "Chat". Mandatory for Telegram chats. Not used for WhatsApp chats.
description	no	string(255)	The description of the "Chat" (Telegram only).
createdBy	no	string(50)	The creator of the "Chat".
phone	yes (whatsapp)	string	The phone number of the WhatsApp recipient, in international format. Mandatory for WhatsApp chats.
webhooks	no	array	Webhook events to subscribe to for this "Chat" (Telegram only). Valid values: "chat-created" and "user-join".

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 "Chat" creation is completed asynchronously: "chatId" is the identifier of the new "Chat" and "parentProcessId" identifies the background process that completes the creation.

"Chat" detail

To be able to get the detailed information of a "Chat"

HTTP Request

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

As response, you will get the following JSON object:


                {
    "id": "9a983789-1709-4543-aa31-a02867680017",
    "isActive": true,
    "service": "telegram",
    "registeredAt": "2024-12-11T08:54:03.000Z",
    "createdBy": "4279566b-ee1b-49ed-bda7-046bd68c11d1",
    "title": [
        {
            "value": "Example chat title",
            "contentType": "text/plain",
            "capturedAt": "2024-12-11T08:54:21.898Z"
        }
    ],
    "participants": [
        {
            "id": "5a9b042b-36ca-4aab-ba50-7ceda030d33f",
            "userProperties": {
                "firstname": "example_bot",
                "username": "example_bot"
            },
            "participations": [
                {
                    "isActive": true,
                    "joinedAt": "2024-12-11T08:54:12.000Z",
                    "invitedBy": "ba2cc0a8-841c-49d3-9c30-418e955f06ff"
                }
            ]
        },
        {
            "id": "ba2cc0a8-841c-49d3-9c30-418e955f06ff",
            "userProperties": {
                "username": "example_user"
            },
            "participations": [
                {
                    "isActive": true,
                    "joinedAt": "2024-12-11T08:54:21.898Z"
                }
            ]
        }
    ]
}

Where:

HTTP Response parameters

Parameter	Datatype	Description
id	UUID	An identification for the "Chat". UUID V4
isActive	bool	If the Chat is active or not
service	string(255)	The provider used to create the "Chat"
registeredAt	string(50)	The timestamp of the creation of the Chat.
createdBy	string(50)	The creator of the "Chat"
title	array	An array with the different titles that the "Chat" has had.
participants	array	An array with the different participants that the "Chat" has had.

"Chat" list

To be able to get the list of "Chats"

HTTP Request

GET /api/v1/private/chats

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
id	no	UUID	Filter by "Chat" identifier.
isActive	no	bool	Filter by active/inactive "Chats".
service	no	string	Filter by provider: "telegram" or "whatsapp".
title	no	string	Filter by "Chat" title.
createdBy	no	string	Filter by the creator of the "Chat".
fromDate	no	timestamp	Return "Chats" registered from this date onwards.
toDate	no	timestamp	Return "Chats" registered up to this date.
users	no	array	Filter by participant users of the "Chat".

As response, you will get the same information as in the "Chat" detail but with an array. Following JSON object:


                {
    "records": [
        {
            "id": "9a983789-1709-4543-aa31-a02867680017",
            "isActive": true,
            "service": "telegram",
            "createdBy": "4279566b-ee1b-49ed-bda7-046bd68c11d1",
            "registeredAt": "2024-12-11T08:54:03",
            "title": [
                {
                    "value": "Example chat title",
                    "contentType": "text/plain",
                    "capturedAt": "2024-12-11T08:54:21.898Z"
                }
            ],
            "participants": [
                {
                    "id": "5a9b042b-36ca-4aab-ba50-7ceda030d33f",
                    "userProperties": {
                        "firstname": "example_bot",
                        "username": "example_bot"
                    },
                    "participations": [
                        {
                            "isActive": true,
                            "joinedAt": "2024-12-11T08:54:12.000Z",
                            "invitedBy": "ba2cc0a8-841c-49d3-9c30-418e955f06ff"
                        }
                    ]
                },
                {
                    "id": "ba2cc0a8-841c-49d3-9c30-418e955f06ff",
                    "userProperties": {
                        "username": "example_user"
                    },
                    "participations": [
                        {
                            "isActive": true,
                            "joinedAt": "2024-12-11T08:54:21.898Z"
                        }
                    ]
                }
            ]
        },
        {
            "id": "3322d043-4f3c-4a85-92fc-4c6876cd9442",
            "isActive": true,
            "service": "telegram",
            "createdBy": "4279566b-ee1b-49ed-bda7-046bd68c11d1",
            "registeredAt": "2024-12-11T07:56:03",
            "title": [
                {
                    "value": "Another example chat title",
                    "contentType": "text/plain",
                    "capturedAt": "2024-12-11T07:56:22.004Z"
                }
            ],
            "participants": [
                {
                    "id": "5a9b042b-36ca-4aab-ba50-7ceda030d33f",
                    "userProperties": {
                        "firstname": "example_bot",
                        "username": "example_bot"
                    },
                    "participations": [
                        {
                            "isActive": true,
                            "joinedAt": "2024-12-11T07:56:12.000Z",
                            "invitedBy": "ba2cc0a8-841c-49d3-9c30-418e955f06ff"
                        }
                    ]
                },
                {
                    "id": "ba2cc0a8-841c-49d3-9c30-418e955f06ff",
                    "userProperties": {
                        "username": "example_user"
                    },
                    "participations": [
                        {
                            "isActive": true,
                            "joinedAt": "2024-12-11T07:56:22.004Z"
                        }
                    ]
                }
            ]
        },
		...
    ],
    "_metadata": {
        "currentPage": 0,
        "totalPages": 42,
        "pageSize": 20,
        "totalRecords": 831
    }
}

Update "Chat" details

To update the details of an existing "Chat".

Note: the previous version of this operation, PATCH /api/v1/private/chats/{chatId}, is deprecated. Use the v2 endpoint described below instead.

HTTP Request

PATCH /api/v2/private/chats/{chatId}

With the following information provided as JSON:

{
        "title": "New title of the chat",
        "description": "New description",
        "isActive": true
    }

Request body parameters

Parameter	Mandatory	Datatype	Description
title	no	string	The new title of the "Chat".
description	no	string	The new description of the "Chat".
isActive	no	bool	Flag to enable/disable the "Chat". Omit to leave unchanged.

This operation follows patch semantics: any field omitted from the request body is left unchanged. Sending an explicit null value in "title" or "description" (to clear the field) is not supported and returns 400 Bad Request.

As response, you will get

204 No Content

Other responses: 400 (validation error), 404 ("Chat" not found) and 409 (unsupported operation).

Delete user from a "Chat"

If you want to delete a user from a "Chat", you can make the following requests:

HTTP Request

DELETE /api/v1/private/chats/{chatId}/participants/{participantId}

As response, you will get

204 No Content

Delete "Chats" in bulk

To delete one or more "Chats". The deletion is an asynchronous process: before the "Chat" data is deleted, the process deactivates the "Chat", sends a final message to it and removes the bot from the conversation.

HTTP Request

DELETE /api/v1/private/bulk/chats

With the following information provided as JSON:

{
        "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "ids": [
            "9a983789-1709-4543-aa31-a02867680017",
            "3322d043-4f3c-4a85-92fc-4c6876cd9442"
        ]
    }

Request body parameters

Parameter	Mandatory	Datatype	Description
requestId	yes	UUID	Identifier of the bulk delete request. UUID V4.
ids	yes	array	The identifiers (UUID) of the "Chats" to delete. Maximum 100 elements.

As response, you will get

204 No Content

which means the deletion request has been accepted and will be processed asynchronously.

Other responses: 404 (some "Chat" was not found) and 409 (some "Chat" is already involved in another process).

Check "Chat" existence

To check whether a "Chat" already exists for a given phone number and service. This is useful to decide whether to create a new "Chat" or reuse an existing one before sending messages.

HTTP Request

GET /api/v1/private/chats/{phone}/service/{service}

Where "phone" is the phone number in international format and "service" is one of WHATSAPP or TELEGRAM.

Note: the phone number travels as part of the URL path; take this into account regarding request logging and privacy on your side.

As response, you will get the following JSON object:

{
    "id": "9a983789-1709-4543-aa31-a02867680017",
    "finished": true
}

HTTP Response parameters

Parameter	Datatype	Description
id	UUID	The identifier of the existing "Chat", if any.
finished	bool	Whether the "Chat" creation process has finished.

Get "Chat" invitation link

If you want get the invitation link of the "Chat", you can make the following requests:

HTTP Request

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

As response, you will get the invitation link as follows:

{
    "service": "telegram",
    "invitation": "https://t.me/xxxxxxxx"
            }

Chat operations

Contents

Introduction

Operations

Register a "Chat"

HTTP Request

Request body parameters

"Chat" detail

HTTP Request

HTTP Response parameters

"Chat" list

HTTP Request

Query parameters

Update "Chat" details

HTTP Request

Request body parameters

Delete user from a "Chat"

HTTP Request

Delete "Chats" in bulk

HTTP Request

Request body parameters

Check "Chat" existence

HTTP Request

HTTP Response parameters

Get "Chat" invitation link

HTTP Request