Working with surveys

Working with Surveys

For each server notification (request), the client should respond as follows:

{
    "type": 2,
    "id": 123456
}

Once the response is sent, the user’s message is marked as read by the bot and a check mark appears in the TrueConf client application.

Client Requests

Send survey

Allows you to send an already created survey to the chat. The survey must be created in advance using one of the following methods:

through the personal area TrueConf Server;
in the client application TrueConf;
using API v4 available in version TrueConf Server 5.5.3.

Request:

{
    "type": 1,
    "id": 5,
    "method": "sendSurvey",
    "payload": {
        "chatId": "5abba630dd1089090ba41c69c7aa34e4ba277a43",
        "replyMessageId": "267d61f2-2ba1-4e88-83ab-bb84415f31b6",
        "content": {
            "url": "https://server.url/webtools/survey",
            "appVersion": 1,
            "path": "employee_testing",
            "title": "Employee survey",
            "description": "{{Survey}}",
            "buttonText": "{{Go to survey}}",
            "secret": "25690753a489f037af09b5cbce417b41374807fe",
            "alt": "📊 <a href='https://server.url/webtools/survey?id=employee_testing&error=autologin_not_supported'>Employee survey</a>"
        }
    }
}

Parameter	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `1`). Corresponds to MESSAGE_TYPE.REQUEST
id	uint32	Yes	Unique request identifier. An incrementable value assigned by the sender, mandatory in each request for subsequent association with the response. Read more here.
method	string	Yes	Command `sendSurvey`
chatId	string	Yes	Chat ID for sending a poll
replyMessageId	string	No	Message ID, if this is a response
url	string	Yes	The survey URL on the server is in the format `https://server.name/webtools/survey`.
appVersion	number	Yes	Surveys version on the server
path	string	Yes	Survey campaign ID
title	string	Yes	Survey Title
description	string	Yes	Survey type — anonymous or non-anonymous. Always contains the string `\{\{Anonymous survey\}\}` or `\{\{Survey\}\}`.
buttonText	string	Yes	The text displayed on the button to proceed to the survey. Always contains the string `\{\{Go to survey\}\}`.
secret	string	Yes	A random string from the message body. It should be generated as a SHA1 hash from the concatenation of the poll name and an arbitrary string.
alt	string	Yes	Alternative link to access the survey. It appears as: `📊 <a href="<url>?id=<path>"><title></a>`, where `<url>`, `<path>`, and `<title>` are replaced with the corresponding values.

Response:

{
    "type": 2,
    "id": 5,
    "payload": {
        "timestamp": 1750168761373,
        "messageId": "f8865b5c-877c-4a55-b175-a667ebf5f007",
        "chatId": "5abba630dd1089090ba41c69c7aa34e4ba277a43"
    }
}

Parameter	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `2`). Corresponds to MESSAGE_TYPE.RESPONSE
id	uint32	Yes	An identifier matching the number sent in the original request, used to link the request and response.
chatId	string	Yes	Chat ID to which the message was sent
messageId	string	Yes	Message ID. This ID can be used later for modifying, forwarding, or deleting the message.
timestamp	uint64	Yes	Timestamp of message sent in UNIX timestamp format with millisecond precision

In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.

Edit survey

Request:

{
    "type": 1,
    "id": 1,
    "method": "editSurvey",
    "payload": {
        "messageId": "f8865b5c-877c-4a55-b175-a667ebf5f007",
        "content": {
            "path": "employee_testing_marketing",
            "title": "Employee survey of the Marketing department",
            "description": "{{Survey}}",
            "buttonText": "{{Go to survey}}",
            "alt": "📊 <a href='https://server.url/webtools/survey?id=employee_testing&error=autologin_not_supported'><title></a>"
        }
    }
}

Parameter	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `1`). Corresponds to MESSAGE_TYPE.REQUEST
id	uint32	Yes	Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here.
method	string	Yes	The `editSurvey` command
messageId	string	Yes	Poll message ID
path	string	Yes	Survey campaign ID
title	string	Yes	Survey Title
description	string	Yes	Survey type — anonymous or non-anonymous. Always contains the string `\{\{Anonymous survey\}\}` or `\{\{Survey\}\}`.
buttonText	string	Yes	Text that will be displayed on the button to proceed to the survey. Always contains the string `\{\{Go to survey\}\}`.
alt	string	Yes	Alternative link to access the survey. It appears as: `📊 <a href="<url>?id=<path>"><title></a>`, where `<url>`, `<path>`, and `<title>` are replaced with the corresponding values.

Response:

{
    "type": 2,
    "id": 1,
    "payload": {
        "messageId": "f8865b5c-877c-4a55-b175-a667ebf5f007",
        "timestamp": 1735314170572
    }
}

Parameter	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `2`). Corresponds to MESSAGE_TYPE.RESPONSE
id	uint32	Yes	An identifier matching the number sent in the original request, used to link the request and response.
messageId	string	Yes	Edited message ID
timestamp	uint64	Yes	Timestamp of the message edit in UNIX timestamp format with millisecond precision.

In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.

Server Notification

New survey

When a new survey is sent in the chat, the client will receive a corresponding notification from the server.

Notification from the server:

{
    "method": "sendMessage",
    "type": 1,
    "id": 11,
    "payload": {
        "chatId": "bd05af54347e04a1c44e70033d35834d4428bb5d",
        "messageId": "d66254de-9d89-4130-8027-c5378f042800",
        "timestamp": 1746029007569,
        "author": {
            "id": "brown@video.example.com",
            "type": 1
        },
        "isEdited": false,
        "box": {
            "id": 4,
            "position": "0"
        },
        "type": 204,
        "content": {
            "url": "<tool_url>?id=...&k=...&mode=popup&call_id=vasya@srv.trueconf.name/1vca3&lang=ru&version=1&app=TrueConf+WebClient&dn=Vasiliy&s=12fee56062786c267cc286045f1fac76",
            "appVersion": 1,
            "path": "some_survey",
            "title": "Meeting survey",
            "description": "{{Survey}}",
            "buttonText": "{{Go to survey}}",
            "secret": "054c1cf18f1e64f4c38b256effedfe18debdcbba",
            "alt": "📊 <a href='https://server.url/webtools/survey?id=some_survey&error=autologin_not_supported'>Meeting survey</a>"
        }
    }
}

The notification about a poll message contains fields corresponding to the Envelope objects. A detailed description of these fields can be found in the section dedicated to working with messages and polls.

Response from client:

{
    "type": 2,
    "id": 123456
}

Field	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `2`). Corresponds to MESSAGE_TYPE.RESPONSE
id	uint32	Yes	Message ID being replied to (see more)