Setting up conversion postbacks for Telegram ecosystem landing links

WARNING

The instructions in this section do not apply to Telegram Ads campaigns. For more information on conversion tracking for links within Telegram in Telegram Ads campaigns, see this section.

Parameters:

• token — a unique token associated with your account. It is available in the AdsGram dashboard and can be regenerated if necessary.

  How to get your token:

  1. Open the AdsGram dashboard.
  2. Click your profile in the top-right corner.
  3. Find the token parameter and click the copy button to copy it.

  

• tgid — the Telegram ID of the user who clicked the advertising link.

• campaignid — the ID of the AdsGram advertising campaign associated with the conversion. It corresponds to the value of the {campaign_id} macro passed in the advertising link. AdsGram inserts the macro value when a user clicks the link.

• goaltype — a parameter that specifies the type of conversion (funnel stage), helping to segment various user actions. It accepts integer values from 1 to 3.

  goaltype usage:

  1. Define the funnel stages in your product or service.
  2. Map the stages to goaltype values:
     • 1. Registration
     • 2. First deposit/purchase
     • 3. Repeat deposit/purchase
  3. Configure conversion tracking for the relevant stages of the user journey.
  4. Add the goaltype parameter to your API request when sending conversion data.
  5. Use this parameter in your analytics to perform a detailed performance analysis by conversion type.

How to set up conversion tracking:

1. Select a campaign. Use an existing active campaign or create a new one.
2. Configure the advertising link. Make sure it contains the {campaign_id} macro.
3. Get your token. Copy your unique token from the AdsGram dashboard.
4. Set up postback delivery. Configure your server to send an API request to AdsGram whenever a user completes a target action.
5. Specify the conversion type. Set the appropriate goaltype value if you want to distinguish between funnel stages.
6. Test the integration. Follow the steps in the Integration testing section below and verify that conversions appear in AdsGram statistics.

API request example upon conversion:

GET
https://api.adsgram.ai/confirm_conversion?token=YOUR_UNIQUE_TOKEN&tgid=98110997&goaltype=2&campaignid=72156

In this example, a conversion of type 2 is reported, such as a first deposit or purchase.

Replace the example values with your actual data:

• YOUR_UNIQUE_TOKEN — your AdsGram account token;
• 98110997 — the Telegram ID of the user who clicked the advertising link;
• 72156 — the ID of your advertising campaign.

Expected response: 200 OK — the conversion has been successfully registered.

Integration testing

To test conversion tracking, follow these steps:

1. Create or select a campaign. Configure the advertising link according to the documentation and make sure it contains the {campaign_id} macro.
2. Wait for clicks. Wait until users have clicked the advertising link several times.
3. Get the user's Telegram ID. Obtain the tgid of a user who clicked the link for the selected campaign.
4. Send a test postback manually. Set goaltype=1 and provide a valid token, the user's Telegram ID in the tgid parameter, and the test campaign ID in the campaignid parameter.
5. Check the result. Verify that the request was processed successfully and that the conversion appears in AdsGram statistics for the selected campaign.

Troubleshooting

• The conversion appears in statistics: the integration is configured correctly and working as expected.
• The server returns an error: check the request URL and the values of the token, tgid, campaignid, and goaltype parameters.
• The request succeeds, but the conversion does not appear: statistics are updated once per hour. If the conversion is still missing after one hour, contact AdsGram Support or your account manager. Be sure to include the request and response logs in your support request.