Set up your service

Before going through this section, you should have a client_id and client_secret for your service. If not, please contact us, we'll be happy to create your service credentials.

Authenticate your service

First, you need to authenticate your service with the OAuth 2.0 protocol. You can follow our authentication guide or use pre-built library to perform the authorization grant and token exchanges for OAuth 2.0.

Request service accounts

Chatflow administrator can add your service in their usage, this process will create a service account specific for your service and a chatflow. This service account will have the authorization to request Algoan API for the chatflow (limited to the scope that your service was defined on). This will also allows you to create a resthook in order to listen to events provided by the execution of the chatflow.

To be sure to not miss new service account, you need to create 2 resthook subscription first with your service for the events service_account_created and service_account_deleted. To do so, you need to follow the next section but with your service credentials.

Example:

const url = `${BASE_URL}/v1/service-accounts`;
const headers = { Authorization: "Bearer" + serviceAccessToken };
// you should connect with your client_id and client_secret to obtain the access_token above.

const authStorage = {}; // you should stores authentication of each service account by subscriptionId to use the associated credentials when you will receive event and perform actions on behalf of the service account for a chatflow.

axios.get(url, { headers }).then((serviceAccounts) => {
  serviceAccounts.forEach((serviceAccount) => {
    // For each serviceAccount, you should:
    // Step 1. Authenticate the service account
    // Step 2. Create one or more resthooks
    // Step 3. Store the result of step 1 & 2 in order to manage to perform actions on behalf of the service account.
    authStorage[subscriptionId] = { serviceAccount, subscription };
  });
});

For more information, see the reference.

Create a resthook subscription

Resthook is a webhook that follows the resthook specifications which considers a webhook as a subscription. You can know more about resthook on the official documentation.

You'll create one resthook (or subscription) for each event.

Resthook is a webhook that follows the resthook specifications which considers a webhook as a subscription. You can know more about resthook on the official documentation.

You'll create one resthook (or subscription) for each event.

const url = `${BASE_URL}/v1/subscriptions`;
const body = {
  target: "https://bankease.com/resthook", // here `bankease.com` is your hostname, `/resthook` is your resthook event: 'products_required' // event you want to subscribe to
};
const headers = { Authorization: "Bearer" + accessToken };
// if you want to listen to `service_account_created` and `service_account_deleted` events, it should be the access token of the service. Otherwise, it should be the access token of the service account.

axios.post(url, body, { headers }).then((res) => {
  const subscriptionId = res.id;
  const subscriptionSecret = res.secret;
});

For more information, see the reference.

Several requests with the same event and resthook will result in only one subscription resource created on our side.

Then patch it to make it active:

const subscriptionId = "...";
const subscriptionSecret = "...";
const url = `${BASE_URL}/v1/subscriptions/${subscriptionId}`;
const body = {
  state: "ACTIVE",
};
const headers = {
  Authorization: "Bearer" + serviceAccountAccessToken,
  "X-Hook-Secret": subscriptionSecret,
};

axios.patch(url, body, { headers });

Great! You are now ready to work with incoming events