> For the complete documentation index, see [llms.txt](https://integrations.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://integrations.impact.com/integration-guides/for-brands/advocate/integrate-sms-messaging-into-your-advocate-referral-program.md). # 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. {% hint style="warning" %} **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. {% endhint %} ```mermaid flowchart TB API["Advocate API"] FE["Your frontend"] HOOK["Your webhook endpoint"] SMS["SMS provider"] API <-->|"Referral code + link"| FE API <-->|"reward.created event"| HOOK FE -->|"Send SMS: link"| SMS HOOK -->|"Send SMS: code (+ link)"| SMS ``` ## 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**](/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user.md#get-tenant_alias-account-accountid-user-userid) 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](/brand-api-reference/advocate-api-reference-v1/reference/user-overview.md). 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](https://integrations.impact.com/integration-guides/for-brands/advocate/pages/eXuv1TBheoZgQxDb75yr#reward.created) | Real-time events — recommended for triggering SMS the moment a reward is issued | | [Rewards API](/brand-api-reference/advocate-api-reference-v1/reference/reward-overview.md) (`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](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/create-and-manage-advocate-webhook-subscriptions) 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. {% stepper %} {% step %} ### Create a subscription You can create a subscription using one of the following methods: * **Using the Webhook API:** [`POST /{tenant_alias}/subscription`](/brand-api-reference/advocate-api-reference-v1/reference/webhook-overview/webhook.md#post-tenant_alias-subscription) with body: {% code expandable="true" %} ```json { "endpointUrl": "https://your-domain.com/webhooks/advocate", "webhookTypes": ["reward.created"], "name": "sms-reward-trigger" } ``` {% endcode %} * **Through the UI:** Refer to [Create & Manage Advocate Webhook Subscriptions](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/create-and-manage-advocate-webhook-subscriptions) for more information. {% endstep %} {% step %} ### Send a test event to confirm delivery `POST /{tenant_alias}/subscription/{url}/test` Every webhook event shares this envelope: {% code expandable="true" %} ```json { "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 } } ``` {% endcode %} {% endstep %} {% step %} ### Extract the reward data When the webhook fires, parse the payload and extract the reward data from the `data` field. {% endstep %} {% step %} ### Send the SMS Send the SMS using the data available in the payload. {% endstep %} {% step %} ### (Optional) Retrieve the participant's referral link If you also need the participant's referral link, call [**Lookup a User**](/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user.md#get-tenant_alias-account-accountid-user-userid) with the `userId` from the payload. {% endstep %} {% endstepper %} ## 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://integrations.impact.com/integration-guides/for-brands/advocate/integrate-sms-messaging-into-your-advocate-referral-program.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.