Integrating with Telegram Bot

📘

Note

Telegram bot is required to enable the channel

To send messages in your Telegram bot using eSputnik, do the following:

1. Create a bot in the @BotFather service, copy the access key, and upload it to eSputnik.
2. Configure a service on your side that will accept contact tokens from your bot and pass them to eSputnik. You can do this in any way that is convenient for you (see the implementation example at the link ).

Access Settings

1. Open @BotFather in Telegram.

2. Send commands

   • /start
   • /newbot

3. Follow the instructions to set up the bot.

4. After creating the bot, you will receive an access token. Copy it.

5. Go to your eSputnik account settings → My bots tab and click Connect Telegram bot.

6. Enter the token in the corresponding field and click Save.

To integrate the already existing bot:

1. Go to My bots tab and click Connect Telegram bot.

2. Click Connect existing bot.

3. Enter the /mybots command in the @BotFather chat, select an existing bot from the list, copy its token, add it to the corresponding field, and click Save.

After connecting the bot, you will receive an application ID (app_uuid) - it must be used in the URL to send a request for adding and updating tokens of your contacts in eSputnik: https://esputnik.com/api/v1/apps/{app_uuid}/tokens.

📘

Note

The number of subscribers of the Telegram bot is shown to the right of the bot's name.

Creating and Updating Contacts

To add or update contact tokens, use the Add application tokens API method (POST type).

JSON request format:

{
  "tokens": [
    "Token"
  ]
}

Contact data format in the request:

{  
	"token": string, 	// required
```
// identifiers to search for contact (at least one is required)
"contactId": Long,
"externalCustomerId": string,
"phone": string,
"email": string
```}

URL to send the request: /v1/apps/{app_uuid}/tokens

A contact is created with all identifiers if there is no contact with such identifiers in the system.

• If the identifiers already exist, they are not created or updated.
• Priority of identifiers for searching contacts in the system: contactId → externalCustomerId → phone → email.
• If a contact is not found by any of the identifiers — contactId → externalCustomerId → phone → email — a new contact is created with all the provided identifiers and the token.
• If a contact is found by any of the identifiers — contactId → externalCustomerId → phone → email — the token will be added to the existing contact. 

Please note that requests using the Add application tokens method do not update existing tokens, but only create new ones. For example, if two requests with the same email address contain two different tokens, both will be written to the contact card.

To update other contact information, use the Add/update a contact or Add/update contacts methods.

📘

After a Telegram bot token is linked to a contact, Telegram Bot can be returned in the channels array by the Get contact and Search for contacts API methods.

Message Statuses

SENT, FAILED, and CLICKED statuses are tracked.

A token will be removed from the contact card upon receiving the FAILED (Forbidden) status, which is sent when the user blocks the bot.