Processing of “start” (UTM) parameters

What is the “start” Parameter?

The start parameter is the only way to pass data to a bot upon its launch. To use it, you need to add the string ?start={your data} to the regular bot link. Such links are called Deep Links.

With it, you can create a referral program or add parameters to track the source of users. You can read more about tracking in our blog.

How do I get this data in the bot?

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

The value that the bot will receive: docs

When the user launches the bot, you receive an Update like Message. It has a text parameter that is equal to /start, in the case of deep link, the text parameter will be equal to /start docs

{
   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 sent to start
   }
}

There is a 64-character limit on the length of the string in the start parameter.

How does Graspil process the “start” Parameter?

Graspil uses this parameter to track the source of users. Telegram does not support additional parameters, so we have added the ability to configure the logic for processing this parameter.

Since only one string can be passed in the “start” parameter, we have added rules that allow this string to be divided into different parameters.

For example, if you need to pass the source of the link and the type of source (such as email), you can use a string like start=source-news1_medium-email and set the necessary settings for its processing.

In Graspil, all such parameters are converted into parameter=value pairs, or in other words, into a table, which can then be used to build reports and filter data.

Param	Value
source	news1
medium	email

You can read about how to set up the processing of the start parameter in the next section.