How-to
Article MarkdownReport an error

How to react to the delivery of a bot message in e-chat (Telegram)?

When a bot writes to a client through e-chat (Telegram), you can find out whether the message actually arrived and run a scenario node: "E-chat (Telegram): message delivered" or "E-chat: message delivery error". For example, create an opportunity in your CRM only after the first message of a campaign is delivered.

Note: e-chat (Telegram) only. This works only for bots connected through e-chat, and only for Telegram. On other channels (your own Telegram bot, Viber, WhatsApp, widget, email) the echat_delivery_tag tag is ignored and the "E-chat (Telegram): message delivered" event is not fired. The "E-chat: message delivery error" event for bot messages also comes from Telegram only.

When you need it

  • A campaign writes to leads, and a lead in the CRM must change its state only after delivery.
  • You need to tell "no such user in Telegram" from "too many requests" or "new contact limit".

Before you start

  • The bot is connected to e-chat (Telegram).
  • A section has a Start node with the Internal events trigger (see Configure internal events).

Steps

1. Tag the message

The tag is the echat_delivery_tag variable set before the message you want to track. Pass a lead id without personal data (not a phone number, not an email).

Two ways:

  • In the scenario: set the echat_delivery_tag variable with a node before the text node.
  • Through call_node: add the echat_delivery_tag field to the request body.
{ "echat_delivery_tag": "lead-77" }

The tag applies to one send: the following messages without a new tag do not return a status. Operator messages and simple "Broadcasts" do not take the tag.

2. Add a node for the event

  1. In the section choose the Start node → Internal events trigger.
  2. Category Messages: E-chat (Telegram): message delivered or E-chat: message delivery error.
  3. Publish the scenario.

3. Use the event data

The node started by the event can use these variables:

Variable Value
{{echat_tag}} The tag from the send. Empty means the event came from an operator message
{{echat_delivery_status}} 1 delivered, 4 error
{{echat_delivery_error_code}} e-chat error code (empty when delivered)
{{echat_delivery_error_description}} The e-chat error text as is
{{echat_delivery_error_reason}} user_not_found, rate_limited, contact_limit or other
{{echat_delivered_message_id}} Message id in e-chat
{{echat_delivered_chat_id}} Recipient chat_id
{{echat_delivered_channel}} Channel (Telegram)

Code 4 does not always mean "the user has no Telegram". Decide by {{echat_delivery_error_reason}}.

Good to know

  • The event node runs in a new session, not in the recipient's dialog. Messages from this node are not sent to the client (they are skipped as successful). Write the result to your CRM or through the API.
  • The event arrives once per message. For one recipient: at most 3 events per hour and at most 3 error events per day.
  • Until e-chat confirms that message ids are unique, send at most one tagged message per second from one bot number.

When no event is fired

No event is fired if: the send failed; the status arrived later than 1 hour after the send; the limits are used up; two messages from one bot number got the same id in e-chat; the store did not answer in time; e-chat sent a status other than 1 and 4 (it is ignored, and the real status after it still fires); or the section has no node for the event (the limit is still spent). In your CRM the lead stays in the "status unknown" state, so plan for that.

Common mistakes

  • No event. Check that the message is tagged and that the section has a node for this very event.
  • Empty {{echat_tag}}. The event was caused by an operator message, not a bot message.

Related: Configure internal events, Internal events reference

Using your own AI agent?Install the open skill so your AI agent can work with current official ConnectiveOne documentation.Get the skillNeed support?Couldn’t find the answer or need help from the ConnectiveOne team? Create a request in Client Portal.Create a request