How to send an invitation using an external platform?

Overview

Rival now supports external distribution webhooks to enable automated delivery of messages via third-party platforms like WhatsApp, mobile apps, or other custom systems. When a message is ready to be sent to a participant, the Rival Platform can trigger a webhook to push that message to your desired channel.

This feature is available upon request. Please reach out to your Customer Success Representative to have it activated for your domain.

Use Cases

Send WhatsApp messages via Twilio
Push in-app notifications to a mobile app
Trigger internal tools or automations via middleware (e.g., Zapier)

How It Works

Instead of delivering messages via SMS or email, Rival can invoke a webhook call with a payload that includes:

A unique identifier (e.g., phone number, external user ID)
The message content
A Rival chat URL

You can use this webhook to route messages through your own system, a CRM, a mobile app, or a third-party communication service like WhatsApp.

Prerequisites

You must have access to the Rival Platform with permission to configure applications and import participants.
A system on your end that can accept incoming webhook payloads and trigger outbound communication.
A list of external subscribers with custom identifiers (e.g., WhatsApp numbers or app member IDs) that can be imported into Rival.
You should collect and store consent from the list of users you will be importing into Rival.

Participant Setup

To target users with webhook-delivered messages:

Navigate to PARTICIPANTS/COMMUNITY → IMPORTS.
Click ACTIONS → Import external community subscribers.
Upload a CSV with:
- external identifier (e.g., your participant id used in your application). Create this external identifier before you upload the csv.
- Any custom profile attributes
You’ll see imported participants in the Community Directory after refreshing the page.

Setting Up Your Application

Go to SETTINGS → APPLICATIONS.
Select an existing application or create a new one.
Generate an API key if one doesn’t exist.
Note the following:
- Header: x-application (use with dev-, staging-, or prod- prefix depending on environment)
- Key token: for authenticating the webhook

Webhook Payload

Each webhook call includes a JSON payload with the following structure:

Top-Level Fields:

messageId – Unique ID for the message
chatId – Chat session ID
chatUrl – Link to launch the chat
unsubscribeUrl – Opt-out link
distributionType – "Invitation" or "Reminder"
message – Message body
domainBrandName – Public-facing name of the domain
distributionId – Distribution tracking ID

Participant Information:

jsonCopyEdit"participant": { "id": "string", "externalIdentifiers": [ { "id": "value", "issuer": "string" } ], "attributes": [ { "label": "string", "valueType": "String | DateTime | SingleChoice", "value": "any", "friendlyValue": "optional readable value", "attribute": { "id": "string", "label": "string", "systemDefined": true | false, "type": "PROFILE", "valueType": "string" } } ] }

This allows your system to:

Identify which user to notify using externalIdentifiers (e.g., WhatsApp number, member ID)
Personalize or filter using attributes (e.g., Occupation, RecontactMethod, TimeZone)
Display or link the chat using chatUrl

When It Triggers

The webhook is fired when a message is sent to a participant with the ‘External’ recontact method.

Example Payload

For learning more about Rival's webhook implementation and structure, refer to the Rival API Documentation.

Next Steps

Once your endpoint is ready, contact Rival Support to register your webhook endpoint to receive external distribution events for your research domain.

See the next article for a detailed example for WhatsApp using Zapier + Twilio.

How to send an invitation via WhatsApp?

Accessing participant id and external identifier