Interactions
Authentication
Use the same publisher’s Bearer API key that served the initial ad.
Authorization: Bearer YOUR_API_KEY
POST /api/v1/ad/interact — request
| Field | Type | Description |
|---|---|---|
tokenrequired | string | Signed token between the first two colons in sk:<token>:<payload>. Use the API key of the publisher that served this ad. |
payloadrequired | string | Action after the second colon, 1–32 characters. It may contain further colons; forward it unchanged. |
user_idrequired | number | Telegram id of the user who tapped (callback_query.from.id). |
chat_type | string | "private", "group" or "supergroup" (callback_query.message.chat.type). Default "private". Drives ephemeral delivery of follow-up scenes in groups. |
callback_query_id | string | Telegram callback query ID. Used for new ephemeral delivery after a group tap. Your client must also call answerCallbackQuery. |
ephemeral_message_id | number | Numeric ephemeral message ID from the callback, when present. Lets the server edit that message in place. |
capabilities | object | Same declaration as on /ad. Without custom_emoji the rendered scene uses a bold brand name. SDK helpers reuse the most recent capabilities supplied to inject(). |
Required fields.
Response and delivery
A successful response contains ok, interaction, send and delivery. Forward send.method and send.params to Telegram with the destination fields from the callback update.
- Private chat: delivery.mode is edit, send.method is editMessageText. Add chat_id and message_id.
- New group follow-up: delivery.mode is ephemeral_new. Preserve ephemeral_message_parameters when calling sendRichMessage and add chat_id.
- Existing ephemeral message: delivery.mode is ephemeral_edit and send.method is editEphemeralMessageText. Preserve receiver_user_id and ephemeral_message_id.
The client must acknowledge the callback with answerCallbackQuery, including when handling an error. A failed ephemeral follow-up must not be resent publicly in the group.
Errors
| Status | Meaning |
|---|---|
400 | Invalid user_id, an empty payload, a payload longer than 32 characters, or an unsupported action. |
401 | Invalid or missing API key. |
403 | The token is missing or invalid, or the impression belongs to another publisher. |
404 | The impression was not found, the campaign is missing, or its rich format or configuration is unavailable. |
429 | The limit of 30 requests per impression within 24 hours has been exceeded. |