Partner Integration

Automatically Provision and Manage Releva Accounts in 5 Easy Steps

This page is indeded for Releva partners. If you are an e-commerce owner and would like to integrate Releva into your shop, please take a look at the Standard Integration instead.

Step 1: Provision Cryptographic Keys

In order to communicate with Releva securely, we need to exchange some secrets. Please follow the procesdure below to generate a key pair.

ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key
# Don't add passphrase
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

This process will produce 2 files – jwtRS256.key (your private key) and jwtRS256.key.pub (your public key). Please keep your private key secret, and send only your public key to support [at] releva ai so we can register it into the system. In exchange, we will send you a partner token, which you must include as part of every request to Releva partner APIs.

Step 2: Provision Releva Account for Client

Whenever a client wises to use Releva, you can provision a Releva account using the following API call:

curl -H 'Content-Type: application/json' -H 'x-rlv-partner-token: <yourPartnerToken>' -XPOST https://releva.ai/api/v0/partners/domains -d'{
  "payload": "....." // a string representing the JSON below signed with your private key
}'

# object to sign
{
  "url": "my-shop.com",
  "name": "My Shop",
  "currencyCode": "USD",
  "contactEmail": "hello@releva.ai",
  "timezoneOffset": "+0300",
  "locale": "en",
  "platform": "custom"
}

A successfully executed request will return a status code 201 if the shop was created within the request, or a status code 200 if the shop already existed prior to the request.

The JSON response will have the following structure:

{
  "domain": {
    "accessToken": "...",
    "secretKey": "....",
    ...
    "pages": [
      {"token": "...", "name": "....", ....},
      ....
    ]
  }
}

It is important to save the acessToken, secerKey, and the list of pages as page name -> token so that you can use them to perform the Standard Integration of the shop that was just provisioned.

Step 2: Obtain Releva Plan Information for Shop

In order to obtain up-to-date plans and pricing information for the shop, please call the following API:

curl -XPOST -H 'content-type: application-json' -H 'x-rlv-partner-token: <yourPartnerToken>' https://releva.ai/api/v0/partners/domains/plans/suggest -d'{
  "payload": "....." // a string representing the JSON below signed with your private key
}'

# object to sign
{
  "shop": "my-shop.com",
}

A successfully executed request will return a status code 200 and the following response. The suggested plan is the plan suggested for this domain based on recorded usage. The current plan is the current plan for this domain, it a plan has been assigned, or null otherwise. The request will also contain the number of trial days remaining for this shop.

{
  "suggestedPlan": {
    "name": "some plan name",
    "basePrice": "19.99",
    "mauIncluded": "125000",
    "pricePerMau": "0.024",
    "emailLimit": "10000",
    "mauLimit": "250000",
    "planId": 1,
    ...
  },
  "currentPlan": {
    "name": "some plan name",
    "basePrice": "19.99",
    "mauIncluded": "125000",
    "pricePerMau": "0.024",
    "emailLimit": "10000",
    "mauLimit": "250000",
    "planId": 1,
    ...
  },
  "trialDays": 14,
  ...
}

Step 3: Confirm Plan Assignment

After you present the plan details to the shop owner, and they agree to the plan terms, you can make the following call to Releva to assign the plan to the shop:

curl -XPOST -H 'content-type: application-json' -H 'x-rlv-partner-token: <yourPartnerToken>' https://releva.ai/api/v0/partners/domains/plans/confirm -d'{
  "payload": "....." // a string representing the JSON below signed with your private key
}'

# object to sign
{
  "shop": "my-shop.com",
   "planId": 1,
   "start": "2022-10-22T00:00:00.000Z",
   "end": "2022-11-22T00:00:00.000Z",
   "trialDays": 14
}

A successful request will return status 200 and the following response:

{
  "plan": {
    "name": "my plan",
    "id": 1,
    ...
  },
  "billingPeriod": {
   "start": "2022-10-22T00:00:00.000Z",
   "end": "2022-11-22T00:00:00.000Z",
   "trialDays": 14,
   ...
  },
  ...
}

Step 4: Single Sign-on (SSO) into the Releva Admin Panel

To allow client stakeloders to log into https://releva.ai/admin and make adjustments to the Releva configuration, you can generate single-sign on links as follows:

https://releva.ai/api/admin/users/partnerSignin/<yourPartnerToken>/<payload>

Where payload is a string representing the JSON below signed with your private key:

{
  "shop": "my-shop.com",
  "user": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john@smith.com",
  }
}

Vising the Single sign-on link will have the following effect:
1. If the user does not yet exist in Releva, it will be created

2. If the user does not have access to this shop, access will be granted

3. If the user was just created, a welcome email will be sent with a link to confirm the Releva user account and set the password.

4.The user will be signed in and reditected to https://releva.ai/admin.

Please note that SSO links have a limited validity so they should be generated on-the-fly and not cached!

Step 5: Implement Account Management Webhooks (Optional)

There are 3 webhooks that you should implement to be able to fully manage account plans:

5.1 Usage Record Create Webhook

Implementing this webhook allows you to receive and store Releva usage records for shop you have provisioned within Releva. Releva will make the following request to your endpoint:

curl -H 'content-type: application/json' -H 'authorization: Bearer <shopSecretKey>' -XPOST https://your-partner-service-url.com/releva/webhooks/usageRecords -d'{
"usageRecords": [
    {
      "day": "2022-10-10",
      "type": "mauAdjustment'/emails/textMessages/pushNotifications/viberMessages",
      "unitPrice": "19.99",
      "amount": "3",
      "billableAmount": "2",
      "totalPrice": "39.98"
    },
    ...
  ]
}'

You can then identify the shop that these usage records are meant for by looking up based on the secret key received in the authorization header.

5.2 Plan Change Request Webhook

Implementing this webhook allows Releva to prompt a client to upgrade to a more expensive plan when they have reached the limit of their plan. Releva will make the following request to your endpoint:

curl -H 'content-type: application/json' -H 'authorization: Bearer <shopSecretKey>' -XPOST https://your-partner-service-url.com/releva/webhooks/plan 

To fully implement the workflow, you should first look up the corresponding shop by the secret key received in the authorization header. Then, you should communicate to the client stakeholders (either via email or via your web interface) that it’s time to upgrade. You can use the Plan suggest API (See Step 2) to show them their current plan and the new suggested plan, and then collect consent for the new plan and confirm it in releva using the Plan Confirm API (See Step 3). This concludes the workflow for client upgrades.

5.3 Addon Purchase Webhook

In addition to prompting users to change to a more expensive plans, Releva may prompt them to purchase additional packages for messaging, for example for the additional purchase of 10,000 emails if they are close to reaching the limit of their plan.

curl -H 'content-type: application/json' -H 'authorization: Bearer <shopSecretKey>' -XPOST https://your-partner-service-url.com/releva/webhooks/addon -d'{
"type": "emails"
}'

Once your service receives this request, it should perform the following API call to Releva to retrieve the available addons that may be purchased and then present them to the client. You can retrieve the shop by looking up based on he value of the secret key in the authorization header in the webhook invocation.

curl -XPOST -H 'content-type: application-json' -H 'x-rlv-partner-token: <yourPartnerToken>' https://releva.ai/api/v0/partners/domains/usageCredits/suggest -d'{
  "payload": "....." // a string representing the JSON below signed with your private key
}'

# object to sign
{
  "shop": "my-shop.com",
  "type": "email"
}

If the request is successful you will receive status 200 and the following response:

{
  "options": [
    {
      "amount": 10000,
      "price": "19.99",
    },
    {
      "amount": 20000,
      "price": "29.99",
    },
    ...
  ],
  "limit": "120000",
  "recordedUsage": "10000"
}

You can then present this information to the client stakeolders, and once they approve an addon purchase, you need to register it in Releva as follows:

curl -XPOST -H 'content-type: application-json' -H 'x-rlv-partner-token: <yourPartnerToken>' https://releva.ai/api/v0/partners/domains/usageCredits/confirm -d'{
  "payload": "....." // a string representing the JSON below signed with your private key
}'

# object to sign
{
  "shop": "my-shop.com",
  "type": "email",
  "amount": 20000,
  "price": "19.99"
}

If the request is successful you will receive a 200 status and the following response:

{
  "type": "email",
  "amount": 20000,
  "price": "19.99"
}

That’s all, folks!

Appendix: Toggling Shop Integrations

If you wish to pause a shop integration, you may do so using the request below. Pausing the integration will stop both the frontend and backend integrations, and will therefore stop the accumulation of usage charges.

curl -XPUT -H 'content-type: application-json' -H 'x-rlv-partner-token: <yourPartnerToken>' https://releva.ai/api/v0/partners/domains -d'{
  "payload": "....." // a string representing the JSON below signed with your private key
}'

# object to sign
{
  "shop": "my-shop.com",
  "running":false
}

To resume a shop integration, use the same request as the one above but change the “running” field to true.