Processing start parameters (UTM)

What is the start parameter?

The start parameter is the only way to pass data to the bot when it's launched. To use it, you need to add the string ?start={ your data } to a regular bot link — such links are called Deep links.

You can use it to build a referral program or add parameters for tracking user sources. You can read more about tracking in our blog.

How do I get this data in the bot?

Example bot link: https://t.me/Graspil_bot?start=docs

The value the bot receives: docs

When the user launches the bot, you receive an Update of type Message. It contains a text parameter equal to /start; in the case of a deep link, the text parameter will equal /start docs

Example

{
   update_id":10000,
   "message":{
     "date":1441645532,
     "chat":{
        "last_name":"Test Lastname",
        "id":1111111,
        "first_name":"Test",
        "username":"Test"
     },
     "message_id":1365,
     "from":{
        "last_name":"Test Lastname",
        "id":1111111,
        "first_name":"Test",
        "username":"Test"
     },
     "text":"/start docs" // <----- data passed in start
   }
}

There's a 64-character limit on the length of the string in the start parameter

How does graspil handle the start parameter?

Graspil uses this parameter to track user sources. Telegram doesn't support additional parameters, so we've added the ability to configure how this parameter is processed.

Since start can only carry a single string, we've added rules that let you split such a string into separate parameters.

For example, you need to pass the referral source and the source type (e.g. email). To do this, you can use a string like start=source-news1_medium-email and set up the appropriate processing rules.

In graspil, all such parameters are converted into parameter=value pairs — in other words, into a table that you can then work with (build reports, filter data).

Parameter	Value
source	news1
medium	email

You can read about how to configure start parameter processing in the next section