# Working with Polls

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

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 Required Description
type uint32 Yes Type of message (default 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sending side, mandatory in each request for subsequent linking with the response. More details read here.
method string Yes Command sendSurvey
chatId string Yes Chat identifier for sending the survey
replyMessageId string No Message identifier if this is a reply
url string Yes String URL for surveys on the server, formatted as https://server.name/webtools/survey
appVersion number Yes Version of the surveys on the server
path string Yes Survey campaign identifier
title string Yes Survey title
description string Yes Type of survey — anonymous or non-anonymous. Always contains the string \{\{Anonymous survey\}\} or \{\{Survey\}\}
buttonText string Yes Text displayed on the button to proceed to the survey. Always contains the string \{\{Go to survey\}\}
secret string Yes Random string from the message body. Must be generated as a SHA1 hash from the concatenation of the survey title and an arbitrary string.
alt string Yes Alternative link to the survey. Formatted as: 📊 <a href="<url>?id=<path>"><title></a>, where the respective values are substituted for <url>, <path>, and <title>.

Answer:

{
    "type": 2,
    "id": 5,
    "payload": {
        "timestamp": 1750168761373,
        "messageId": "f8865b5c-877c-4a55-b175-a667ebf5f007",
        "chatId": "5abba630dd1089090ba41c69c7aa34e4ba277a43"
    }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier matching the number sent in the original request, used to link request and response
chatId string Yes Identifier of the chat where the message was sent
messageId string Yes Message identifier. This identifier can be used for further modification, forwarding, or deletion of the message
timestamp uint64 Yes Message sending timestamp in UNIX timestamp format with millisecond precision

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

# Edit poll

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 Req. Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sender, required in each request for subsequent binding with the response. Read more here
method string Yes Command editSurvey
messageId string Yes Survey message identifier
path string Yes Survey campaign identifier
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 to be displayed on the button to proceed to the survey. Always contains the string \{\{Go to survey\}\}
alt string Yes Alternative link to proceed to the survey. It appears as: 📊 <a href="<url>?id=<path>"><title></a>, where <url>, <path>, and <title> are replaced with the corresponding values.

Answer:

{
    "type": 2,
    "id": 1,
    "payload": {
        "messageId": "f8865b5c-877c-4a55-b175-a667ebf5f007",
        "timestamp": 1735314170572
    }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes An identifier that matches the number sent in the original request, used for linking the request and response
messageId string Yes Identifier of the edited message
timestamp uint64 Yes Timestamp of the message edit in UNIX timestamp format with millisecond precision

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

# Server Notification

# New poll

Message 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 message with a survey includes fields corresponding to the Envelope objects. A detailed description of these fields can be found in the section dedicated to working with messages and surveys.

Response from client:

{
    "type": 2,
    "id": 123456
}
Field Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier of the message being responded to (see details)