When setting up your Amplitude Integration with Notivize you must define an endpoint (secured by an API key) that will be used to retrieve all the information needed for sending a notification. In exchange for Amplitude cohort user ids, you will return recipient information and context variables used in the template of your notification.

Here is the API Specification to build your endpoint:

API Headers

Notivize will send the following headers when making a POST request against your API endpoint:

Name	Values
Authorization	Basic {{ api_key }}
Content-Type	application/json
Accept	application/json

API Body

Notivize will send the following JSON body:

Name	Value(s)
user_ids	array[string]

Example

{
  user_ids: [
  	"5236489239",
    "8026404105",
    "6557437082",
    "3739884942",
    "0958913505",
    "3911793580",
    "3937292296",
    "1626624548",
    "3752577837",
    "6236286138",
    ...
  ]
}

API Response (expected from your API endpoint)

Notivize expexcts a JSON response containing a list where each item has the following fields:

Name	Value(s)
to	To: object
variables	Variables: object

To

Notivize supports 3 channels with Amplitude (Email, SMS, and Push Notification). You need to set the key/value pair for the channel matching your notification channel. If you send notifications to different channels, you may set all the key/value pairs for which you have data.

Channel	Expected Key
Email	"email"
SMS	"phone"
Push Notification	"token"

Single channel
{
    "email": "acme@example.com"
}

Multiple channels
{
    "email": "acme@example.com",
    "phone": "+13256764532",
    "token": "5684874357487068"
}

Variables

The variables object contains the context variables for the notification template, as well as variables used to evaluate rules and a unique_id. Any extra variables (not used in template or rules) will be ignored. If you don't provide a unique id, we'll use the first non-null value found in the "to" object in order to prevent sending the same notification twice to the same recipient.

Single notification
{
    "first_name": "Fake",
    "last_name": "Name",
    "age": 30,
    "unique_id": "fakename@example.com"
}

With extra fields
{
    "first_name": "Fake",
    "last_name": "Name",
    "age": 30,
    "birthday": "2021/01/01",
    "cart_count": 12,
    "last_visited": "2021/01/01T10:10:00-07:00"
}

Scenario

Notification

Email
<body>
    <h1>Hello {{first_name}}</h1>
    <p>Thanks for reviewing {{review_count}} products.</p>
</body>

Push Notification
Hi {{first_name}} 👋🏻
Thanks for installing the Acme app!

Sms
You wrote {{review_count}} reviews, one more to go before getting a promo code!

Query from Notivize to your endpoint

curl -X POST "https://partner.com/amplitude/user_info" \
     -H "Authorization: Bearer 1234-xxxx-zzzz" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     --data '{"user_ids": ["1234", "5678", "9101"]}'

Response

[
    {
        "to": {
            "token": "1234",
            "email": "fakeemail@example.com",
            "phone": null
        },
        "variables": {
            "unique_id": "user_id_1",
            "first_name": "fake name 1",
            "review_count": 3
        }
    },
    {
        "to": {
            "token": "5678",
            "email": "fakeemail2@example.com",
            "phone": "+13031234567"
        },
        "variables": {
            "unique_id": "user_id_2",
            "first_name": "fake name 2",
            "review_count": 15
        }
    },
    {
        "to": {
            "token": null,
            "email": null,
            "phone": "+13031234567"
        },
        "variables": {
            "unique_id": "user_id_3",
            "first_name": "fake name 3",
            "review_count": 1000
        }
    }
]