To send a message

Attention

The toloka.yandex.com domain will be disabled starting July 1, 2023. Please use the toloka.dev domain for API requests.

Sends a message to Tolokers.

The sent message is added to a new message thread.

Restriction

You can send a maximum of 1 messages per day to mass mail all your users, and 100,000 messages per day when targeting specific Tolokers. Refer to the Rate limiting section for the complete list of the request limitations in Toloka API.

Request

Tip

Try our new API reference: more parameter details, request/response examples, and code samples in various programming languages, including the Toloka-Kit usage samples.

Production version
Sandbox
POST https://toloka.dev/api/v1/message-threads/compose
Authorization: OAuth <OAuth token>
Content-Type: application/JSON

Headers

TitleOverview
AuthorizationA token for account authorization. Add OAuth as a prefix.
Content-TypeSpecifies the data format in the request body.

Request body

Message with a list of recipients
Filter message
{
"topic": {
"EN": "You have got a bonus!"
},
"text": {
"EN": "The bonus was awarded for good job!"
},
"recipients_select_type": "DIRECT",
"recipients_ids": [
"2225cfb24c15b7d691818f5ac9d07f70"
],
"answerable": true
}
ParameterOverview
topicobject | required

Subject of the message. You can enter the subject in multiple languages (the message is sent in the Toloker's language). Format: "<language RU/EN/TR/ID/FR>": "<title text>".
answerable

boolean | required

Whether the message can be responded to:

  • true — Users can respond to the message.
  • false — Users can't respond to the  message.

The default value is true.

textobject | required

Message text. You can enter the text in multiple languages (the message is sent in the Toloker's language). Format: "<language RU/EN/TR/ID/FR>": "<message text>".
recipients_select_type

string | required

Method for selecting recipients:

  • DIRECT — Specify Toloker IDs.
  • FILTER — Use a filter to select Tolokers.
  • ALL — Send the message to all Tolokers who have tried to complete your tasks at least once.
recipients_idsobject | required if

Required if recipients_select_typ. The list of IDs of Tolokers who will receive the message.

Response

In response, you will receive a message as a new thread.

{
"id": "558110f401d292324c0da8bd",
"topic": {
"EN": "You received a bonus!"
},
"interlocutors_inlined": true,
"interlocutors": [
{
"id": "111bd25f1bb71f37844e2a9355faad67",
"role": "REQUESTER",
"myself": true
},
{
"id": "2225cfb24c15b7d691818f5ac9d07f70",
"role": "USER"
}
],
"messages_inlined": true,
"messages": [
{
"text": {
"EN": "Thank you!"
},
"from": {
"id": "2225cfb24c15b7d691818f5ac9d07f70",
"role": "USER"
},
"created": "2017-01-31T11:02:31"
{
"text": {
"EN": "You received a bonus for doing a good job!"
},
"from": {
"id": "111bd25f1bb71f37844e2a9355faad67",
"role": "REQUESTER",
"myself": true
},
"created": "2017-01-31T09:38:01"
}
],
"compose_details": {
"recipients_select_type": "DIRECT",
"recipients_ids": [
"2225cfb24c15b7d691818f5ac9d07f70"
]
},
"answerable": true,
"folders": [
"INBOX",
"OUTBOX"
],
"created": "2017-01-31T09:38:01"
}
ParameterOverview
idstring

Message thread ID.
topicobject

Message thread title.
interlocutors_inlined

boolean

Access to information about the sender and recipients.

  • true — Information is available in the interlocutors field.
  • false — Information is available in a separate request.
interlocutors[]array of objects

Information about the sender and recipients, sorted by ID.
interlocutors.idstring

ID of the sender or recipient.
interlocutors.role

string

Role of the sender or recipient in Toloka:

  • USER — Toloker.
  • REQUESTER — Requester.
  • ADMINISTRATOR — Admin.
  • SYSTEM — For messages sent automatically.
interlocutors.myselfboolean

Indicates a sender or recipient with your ID. If this is your ID, it is set to true.
messages_inlined

boolean

Access to message threads:

  • true — The message is available in the messages field.
  • false — The message is available in a separate request.
messages[]array of objects

Messages in the thread. Messages are sorted by date of creation (newest first).
messages.textobject

Message text.
messages.fromstring

Information about the sender.
messages.from.idstring

The sender's ID.
messages.from.role

string

The sender's role in Toloka:

  • USER — Toloker.
  • REQUESTER — Requester.
  • ADMINISTRATOR — Admin.
  • SYSTEM — For messages sent automatically.
messages.from.myselfboolean

Marks a sender with your ID. If you are the sender, it is set to true.
messages.createdstring

Date the message was created.
compose_detailsobject

For messages that you sent: details of the POST request for creating the message.
compose_details.recipients_select_type

string

Method for selecting recipients:

  • DIRECT — Specify Toloker IDs.
  • FILTER — Use a filter to select Tolokers.
  • ALL — Send the message to all Tolokers who have tried to complete a task at least once.
compose_details.recipients_idsobject

The list of IDs of Tolokers who will receive the message.
compose_details.recipients_filterobject

Filter for selecting recipients.
answerable

boolean

Whether the message can be responded to:

  • true — The Toloker can respond to the message.
  • false — The Toloker cannot respond to the message.
folders[]

array of objects

Folders where the thread is located:

  • INBOX — Inbox.
  • OUTBOX — Sent.
  • AUTOMATIC_NOTIFICATION — Notifications.
  • IMPORTANT — Important.
  • UNREAD — Unread.
createdstring

Date the first message in the thread was created.
Contact support
Toloka API
OverviewAccessing the APIRate limiting
Quick start
Reference
Project
Pools
Training
Subscriptions to events
Toloker selection
Ways to upload tasks
Tasks
Task suites
Tracking operations
Getting responses
Checking completed tasks
Bonuses
Messages for Tolokers
Various parameters
Libraries