Integrate SMS Messaging into Your Advocate Referral Program

impact.com doesn't offer a native SMS integration for Advocate, but you can build one using the Advocate REST API and webhooks. This guide explains how to retrieve referral links and discount codes and how to trigger SMS messages at key points in a referral flow. For example, sending an invite, delivering a friend's discount code, or confirming a reward.

Important: This integration guide assumes familiarity with REST APIs and webhooks; non-technical users will likely find this integration difficult to implement without developer support.

Why build an SMS integration

Referral programs often perform best over SMS, but Advocate doesn't have the capability to send SMS messages directly. Instead, you connect Advocate's data to your own SMS provider, e.g., Twilio, Attentive, using API calls and webhook events. A typical SMS referral flow strings together several messages, such as:

1. An initial "refer your friends" message to existing customers.
2. A "here's your code" message when a referred friend joins the program.
3. A reminder if a referred friend hasn't completed a purchase.
4. A confirmation when a referred friend places an order.
5. A reward message to the original referrer once they qualify.

Each message depends on knowing what data to fetch and when to fetch it. The rest of this guide covers both.

Common integration patterns

• Send a referral link on demand — call Lookup a User when a participant requests their link, e.g., tapping "invite friends" in an app, then send it by SMS.
• Trigger an SMS when a reward is created — subscribe to reward.created, extract the discount code, and fire the SMS immediately.
• Chain multiple messages from one trigger — use the data from the initial webhook to schedule follow-up messages (reminders, confirmations) through your SMS provider or a job scheduler.

Data you can access for SMS messages

Two pieces of data drive most SMS referral flows: a participant's referral link and their discount code. They come from different parts of the API.

Referral links

Retrieve a participant's referral link with the Lookup a User endpoint. This is an on-demand call — use it whenever you need a share link to include in an SMS.

• GET /{tenant_alias}/account/{accountId}/user/{userId} — look up by user ID
• GET /{tenant_alias}/user?referralCode={code} — look up by referral code

Both return referralCode and shareLinks (the participant's referral links, organized by share medium — including SMS — and engagement type).

Discount codes

Discount codes can be retrieved two ways:

Method	Recommendation
reward.created webhook	Real-time events — recommended for triggering SMS the moment a reward is issued
Rewards API (GET /{tenant_alias}/reward or GET /{tenant_alias}/reward/{id})	On-demand lookups, e.g. for support tooling or reconciliation

The webhook payload does not include the participant's referral link, so most flows that need both a code and a link end up calling the Lookup a User endpoint as a follow-up.

Trigger an SMS with the reward.created webhook

reward.created fires when a reward becomes available, for example, when a referred friend completes their first purchase and the reward pending period has ended. One webhook subscription covers every reward-issuing scenario, e.g., a friend opting in, or a referrer qualifying for a reward, so you don't need separate subscriptions per scenario.

Delivery order and timing between events aren't guaranteed, so don't build logic that depends on webhooks arriving in a specific sequence. If your endpoint doesn't return a 200 response, impact.com retries delivery hourly for up to approximately 3 days (72 attempts) before giving up.

1

Create a subscription

You can create a subscription using one of the following methods:

• Using the Webhook API: POST /{tenant_alias}/subscription with body:

{
"endpointUrl": "https://your-domain.com/webhooks/advocate", 
"webhookTypes": ["reward.created"], 
"name": "sms-reward-trigger"
}

• Through the UI: Refer to Create & Manage Advocate Webhook Subscriptions for more information.

2

Send a test event to confirm delivery

POST /{tenant_alias}/subscription/{url}/test

Every webhook event shares this envelope:

{
  "id": "evt_3f2a1c9e",          // Unique identifier for this event
  "type": "FUELTANK",            // Webhook event type
  "fuelTankCode": "FRIEND8389KP3", // The specific code associated with the fueltank reward
  "tenantAlias": "yourbrand",    // The tenant this event belongs to
  "live": false,                  // true for Live tenant events, false for Test
  "created": 1731542400000,      // Event creation timestamp, in milliseconds
  "data": {                      // Event-specific payload — the reward object for reward.created
    "id": "rew_8d4b2f11",         // Unique reward identifier
    "type": "PCT_DISCOUNT",       // Reward type: PCT_DISCOUNT, CREDIT, or FUELTANK
    "userId": "usr_7a1c9e2b",     // Owner of the reward — pass to Lookup a User for the referral link
    "referralId": "ref_5e9d4a01", // The referral that triggered this reward
    "amount": 15,                 // Quantity earned
    "currency": "USD",            // Currency for credit-based rewards
    "dateGiven": "2026-07-10T14:32:00Z" // When the reward was issued
  }
}

3

Extract the reward data

When the webhook fires, parse the payload and extract the reward data from the data field.

4

Send the SMS

Send the SMS using the data available in the payload.

5

(Optional) Retrieve the participant's referral link

If you also need the participant's referral link, call Lookup a User with the userId from the payload.

Implementation checklist

• Create a webhook subscription for reward.created and confirm it with a test event
• Parse the webhook payload and validate the data object before using it
• Handle delivery failures — your endpoint should return 200 promptly, since non-200 responses trigger hourly retries for up to 3 days
• Call Lookup a User when you need a referral link alongside a discount code
• Test the full flow end-to-end with your SMS provider before going live