In order to get started with the Account Portal API you need to register or to be invited to one of the existing organization.

Please contact support@get.chat if you want to be approved as an official get.chat partner. You can ask your account manager, if you have one, to get a working set of credentials for you.

User

The entity that logs in with a username and password to use Account Portal API with the received access token. It can be considered as a single person that has access to multiple organizations.

A user can be promoted to be a partner of the organization. This means that it's authorized to create customer organizations that will be linked to their partner organization and do actions on their behalf.

Organization

The entity that represents a company/organization with multiple users.

Package

The entity that represents a set of features that can be deployed for a given organization. At the moment the only package available to deploy on the Account Portal API is the get.chat inbox. In the near future, we expect to add several integrations like Hubspot.

Stack

The entity that groups different applications for a given organization that interact with each other. For example, if you want an organization to connect their get.chat inbox with Hubspot you will deploy first the inbox on a stack, and then you will deploy the Hubspot application on the same stack.

INBOX API: https://get.chat/docs

Application

The entity basically represents the deployed instance of the package with the provided configuration.

When you want to deploy an application you must pass all required variables for the package type. This guideline will help you to understand what are those variables about and who can use them.

Parameter necessity

◆ - Required
◈ - Recommended
◇ - Optional

👤 Role

Role of the user who requests to create / update the application.

🔓️ Access

The section that shows if a parameter is allowed to be passed.

🚫 Restrictions

ℹ️ Each limitation could be personalized for the organization so If you would need to raise any, please reach out to support.

There might be a case when the parameter is allowed to be passed but with some limitations.

◆ d360_api_key (str)

⚠️There is a temporary limitation that d360_api_key (360dialog API Key) for the Inbox package could be passed only by Partner+ roles. Soon it will be available again to both Owner and Maintainer.

360dialog (WABA Proxy) API Key used instead of direct connection to WABA Stack

◇ admin_email (str)

E-mail to which an activation URL will be sent so that new users can log in and set their password. If no email was provided we take one from the authenticated user.

◇ max_seats (int)

Maximum number of seats inbox quota. Limitation that does not allow you to create more users than this number.

◇ max_messages (int)

Quota of messages stored in the inbox. If number of messages exceeds this number, the oldest messages exceeding the limit are deleted.

◇ admin_user (str)

When provided, an admin user will be created for the owner of this inbox. This is the first user that is needed in order to access and manage the inbox.

◇ configurator_user (str)

Configurator username of the partner user for configuration purpose.

◇ configurator_webhook_url (str)

Webhook that should be called with configurator credentials. This parameter is required when configurator username is provided.

◇ configurator_webhook_headers (JSONStr)

Additional parameter that allows setting optional webhook headers. e.g. "{\"Authorization\": \"Basic 123\"}"

This document is targeted at partners that want to see a step-by-step tutorial for setting up an Inbox for a new organization. In this tutorial, you will use the Account Portal API from the shell (if you prefer another tool that allows you to send HTTP requests, you can of course use that).

In order to use all later commands, you will need an access token. You can use your account credentials to obtain one.

$ curl --request POST \
    --url https://account-api.get.chat/account/login \
    --header 'Content-Type: application/json' \
    --data '{
    "email": "user@example.com",
    "password": "string"
  }'

This is an example response:

{
  "id_token": "id_token",
  "access_token": "access_token",
  "token_type": "Bearer",
  "expires_in": 604800
}

Note that this token expires after the number of seconds found in the response. In this example, it is seven days, after which a new token would have to be obtained.

Remember to use the access token you gained in step 1 in the Authorization header.

By providing organization_id in the path you are connecting a newly created organization to the organization you are a partner in. IDs could be received by calling the list of organizations you have access to and finding the new one you've just created.

$ curl --request POST \
  --url https://account-api.get.chat/account/organizations/{organization_id}/customers \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json'

An inbox can have multiple packages attached to it, over which you have control; an inbox instance and its set of selected packages is what we call a stack. For a new organization, you need to create their stack like this (substitute access_token and organization_id with the appropriate values from step 1 and step 2):

In case, you are unable to save our ID anywhere to get information later we are supporting the optional partner_meta key-value pairs field where you can put any info you know how to deal with.

$ curl --request POST \
  --url https://account-api.get.chat/integration/organizations/{organization_id}/stacks \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "partner_meta": {}
  }'

You will get a response like this immediately, but it might take a while until it is actually ready:

{
  "id": 0,
  "user_status": "REQUESTED",
  "is_locked": true,
  "name": "string",
  "partner_meta": {},
  "organization_id": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z"
}

You will need the id from this response in step 5, we will refer to it as stack_id. Also, it may take a while until the stack is set up internally. Regularly request this to check on the stack's current status; you can continue once the user_status is READY:

$ curl --request GET \
  --url https://account-api.get.chat/integration/stacks/{stack_id} \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json'

The services you can install on a stack are called packages; this name was already used in step 3. In order to choose what you can install on your organization's stack, you can obtain the package list like this:

$ curl --request GET \
  --url 'https://account-api.get.chat/integration/packages?paginated=true' \
  --header 'Content-Type: application/json'

[Attention] Deprecated paginated query parameter by default is false. Soon this endpoint will support only paginated results.

The response will look similar to this:

{
  "data": [
    {
      "id": 1,
      "created_at": "2021-12-21T11:32:21Z",
      "modified_at": "2021-12-21T11:32:21Z",
      "name": "Inbox",
      "type": "inbox"
    },
    {
      "id": 2,
      "created_at": "2022-02-02T09:31:12Z",
      "modified_at": "2022-02-02T09:31:12Z",
      "name": "HubSpot",
      "type": "_hubspot"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 20,
    "page": 1,
    "pages": 1,
    "count": 2
  },
  "filters": {
    "deleted_at[eq]": null,
    "paginated": true
  },
  "sort": [
    "+id"
  ]
}

Installing the Inbox package is mandatory, while the others will depend on your organization's needs. So let us go to the final step.

Installing a package on a stack is called an application. It is done like this and requires the access token from step 1, the stack_id from step 3, and the package_id from step 4.

In addition, you need d360_api_key (360dialog API key). All available Inbox parameters might be found here.

As in the situation with the stack (step 3) application also supports the optional partner_meta key-value pairs field.

$ curl --request POST \
  --url https://account-api.get.chat/integration/stacks/{stack_id}/applications \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
  "package_id": 0,
  "settings": {
    "d360_api_key": "example_api_key"
  },
  "partner_meta": {}
}'

Once again, creating an application will immediately return a response with a user_status key-value pair whose value will initially be REQUESTED. The response will also contain an id key-value pair whose value can be used to regularly check for when the Inbox is ready to be used (referred to in the next snippet as application_id). Use this to get an update on the setup status:

$ curl --request GET \
  --url https://account-api.get.chat/integration/applications/{application_id} \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json'

After successfully deploying the inbox package, the owner email address (value passed to the admin_email) will receive an email with an activation link to start using the inbox. You are all set!

Where do I get the 360dialog API key from?

360dialog Integrated Onboarding allows you to offer a completely integrated signup experience to customers. After it is implemented, the Connect Button should trigger a pop-up which the customer will use to create their WhatsApp Business API account.

After the signup is completed, the customer will give you permission to manage their account, which will send their API key to you via API connection. This means that the customer won't need to copy and share their API key with you. Read more here

If you are still not a 360dialog partner you can join their partnership program here.

Basically, to skip all those steps from Deploy your first inbox guide you may use a shortcut that allows you to do everything in a single endpoint call.

Firstly, you would need to log in into your partner account via Login endpoint.

Once you have done this, use access token to make an authenticated call to the Instant Create Application. Settings that must be passed on inbox creation you may find in the Deploy Application step.

One of the parameters of the Instant Create Application endpoint is the settings param. This is a key-value configuration that will be passed to the app, at the time of install.

See Application settings / Inbox section for more information about all available settings.

In order to configure your Inbox automatically (create new users yourself, set up groups, set up tags, etc.), you'll need to create your own integration that is running on your servers.

With configurator_* settings you are able to create for yourself a configurator user access. A configurator user has admin permissions to related inbox, with a restriction to reading out messages. When acting as a configurator of one inbox, you are able to perform all administrator-level settings, before handing over the inbox to the end user. Your configurator user should be doing all that, by using Inbox Integration API.

As an example, configurator_* settings options allow you to implement the following automation flow:

1. Create a new Inbox using Instant Create Application with configurator_* parameters inside settings.

   • Provide configurator_user to pick your unique username (Configurator user is invisible to your end users and does not consume seat limitation).
   • Provide configurator_webhook_url to be able to initialize your configurator user with credentials coming from particular inbox.
   • Provide configurator_webhook_headers to restrict your webhook receiver with security headers.

2. After your inbox is created, configurator user is created inside it. You will receive configurator user credentials to your configurator_webhook_url with JSON payload: {"token": "<token>"}. This is the authorization token bound to the configurator user account, that should be used with Inbox Integration API header Authorization: Token <token>. See Accessing the API section in Inbox Integration API documentation.

3. After your automation received the token, it is possible to access entire Inbox Integration API with this token, and configure your inbox freely.

4. As an example, you can create an end user account with createNewUser endpoint.

5. Successful response of createNewUser, returns activation_url as a parameter. You should use this URL to activate your end user's account.

   There are two options:

   • Pass this URL to your user somehow (e.g. via e-mail), so that the user can set their password themselves.
   • In case you don't want the end user to set the password, call the HTTP GET method on the activation_url link yourself automatically, and done - your user is activated! Further changes to the user's password can be done using changeUserPassword endpoint.

The inbox can be embedded inside any web application using an iframe element.

<iframe src="https://your_stack_name.inbox.platform.get.chat/main/" title="My cool WhatsApp Inbox"></iframe>

When the inbox is embedded in a small area it's sometimes very useful to just render a specific element. When loading a conversation a URL, a URL parameter (chatonly=1) can be added to remove the chat list on the left.

<iframe src="https://your_stack_name.inbox.platform.get.chat/main/chat/34XXXXXXXXX?chatonly=1" title="My cool WhatsApp Inbox - Conversation #1"></iframe>

The inbox UI is open source. https://github.com/get-chat/web-app

Direct connection

Each inbox has its own domain so a direct connection can be established. Is it necessary to have the same domain for it to work?

Inbox routing

The request is sent to the inbox router and using a URL parameter it is forwarded to the relevant inbox.

This article will help you to set up the webhook URL where all events will be sent.

Partner is able to receive both his own events and events of the customers' organizations if webhook_url is set.

The structure of the event request looks like the following:

POST {webhook_url}

{
  "event": "event.name",
  "data": {} 
}

There are a few events that we support and send to the partners and customers.

Stack events

{
  "event": "stack.{action}.{status}",
  "data": {
    "application_quota": 1,
    "organization_id": 1,
    "created_at": "2000-01-01T00:00:00Z",
    "id": 1,
    "is_deployed": true,
    "is_locked": false,
    "locked": null,
    "modified_at": "2000-01-01T00:00:00Z",
    "name": "64a54c6d72df",
    "platform_meta": {
      "cluster_id": 1,
      "id": 1,
      "name": "000000000000",
      "namespace": "stack-1-00000"
    },
    "status": "READY",
    "user_status": "READY"
  }
}

Deployment

• stack.deployment.succeeded
• stack.deployemnt.failed

Modification

• stack.modification.succeeded
• stack.modification.failed

Destruction

• stack.destruction.succeeded
• stack.destruction.failed

Application events

{
  "event": "application.{action}.{status}",
  "data": {
    "created_at": "2000-01-01T00:00:00Z",
    "domain": "000000000000.inbox.platform.get.chat",
    "id": 1,
    "is_deployed": true,
    "is_locked": false,
    "locked": null,
    "modified_at": "2000-01-01T00:00:00Z",
    "package_id": 1,
    "platform_meta": {
      "domain": "000000000000.inbox.platform.get.chat",
      "id": 1,
      "version": "2000.01.01"
    },
    "stack_id": 1,
    "status": "READY",
    "user_status": "READY",
    "uuid": "00000000-0000-4000-8000-000000000000"
  }
}

Deployment

• application.deployment.succeeded
• application.deployemnt.failed

Modification

• application.modification.succeeded
• application.modification.failed

Destruction

• application.destruction.succeeded
• application.destruction.failed

Step 1: Logging in

In order to use all later commands, you will need an access token. You can use your account credentials to obtain one.

$ curl --request POST \
  --url https://account-api.get.chat/account/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "user@example.com",
    "password": "string"
  }'

This is an example response:

{
  "id_token": "id_token",
  "access_token": "access_token",
  "token_type": "Bearer",
  "expires_in": 604800
}

Note that this token expires after the number of seconds found in the response. In this example, it is seven days, after which a new token would have to be obtained.

Step 2: Get your organization ID to update

To get your available Organization IDs you would need to call the organizations endpoint and extract id from the response.

$ curl --request GET \
  --url https://account-api.get.chat/account/organizations \
  --header 'Authorization: Bearer {access_token}'

This is an example response:

{
  "data": [
    {
      "id": 1,
      "created_at": "2000-01-01T00:00:00Z",
      "modified_at": "2000-01-01T00:00:00Z",
      "name": "string",
      "stack_quota": 10,
      "webhook_url": "http://example.com"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "page": 1,
    "pages": 1,
    "count": 1
  },
  "filters": {},
  "sort": [
    "+id"
  ]
}

Step 3: Update your organization's webhook_url

Each partner may update his webhook_url to receive events. webhook_url MUST be a valid URL including the schema (path is optional), for example https://example.com/webhook.

$ curl --request PATCH \
  --url https://account-api.get.chat/account/organizations/{organization_id} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "webhook_url": "https://example.com/webhook"
  }'

This article explains how to configure and deploy your own customized version of the Inbox WebApp.

WebApp code is publicly available to clone from GitHub:

git clone https://gitlab.com/get.chat/web-app.git

Before you run it, you must create the config.json file in public folder if it doesn't exist. Please see the public/config.json.tmpl template file.

{
    "API_BASE_URL": "${APP_API_BASE_URL}",
    "APP_SENTRY_DSN": "${APP_SENTRY_DSN}",
    "APP_ENV_NAME": "${APP_ENV_NAME}",
    "APP_NOTIFICATIONS_LIMIT_PER_MINUTE": "${APP_NOTIFICATIONS_LIMIT_PER_MINUTE}",
    "APP_GOOGLE_MAPS_API_KEY": "${APP_GOOGLE_MAPS_API_KEY}"
}

API Base URL

Specify the Rest API URL as the value of API_BASE_URL inside the config.

API_BASE_URL should be set to https://your_inbox_domain/api/v1/ to use same address as get.chat Web App runs on.

Sentry

Sentry is a developer-first error tracking and performance monitoring platform that helps developers see what actually matters, solve quicker, and learn continuously about their applications.

Change Sentry DSN Key

If you forked this project and want to keep Sentry integration enabled, please make sure to use your own Sentry DSN key (https://docs.sentry.io/product/sentry-basics/dsn-explainer/). In order to do this, please go to public/config.json file and replace the value of APP_SENTRY_DSN variable.

Disable Sentry

In order to disable Sentry integration, you can either remove or comment out Sentry.init method inside src/index.js.

// ***IMPORTS***
// Init storage type
initStorageType();

// Load external config and render App
axios
    .get(`/config.json`)
    .then((response) => {
        const config = response.data;

        // It is needed for ChatMessageClass
        window.config = config;

         // Init Sentry
+		// if (!isLocalHost()) {
+		// 	Sentry.init({
+		// 		debug: true,
+		// 		dsn: config.APP_SENTRY_DSN,
+		// 		release: packageJson.version,
+		// 		integrations: [new Integrations.BrowserTracing()],
+		// 		tracesSampleRate: 0.01,
+		// 		beforeSend(event, hint) {
+               // 			// Check if it is an exception, and if so, show the report dialog
+		// 			if (event.exception) {
+		// 				Sentry.showReportDialog({ eventId: event.event_id });
+		// 			}
+		// 			return event;
+		// 		},
+		// 	});
+		// }
-		if (!isLocalHost()) {
-			Sentry.init({
-				debug: true,
-				dsn: config.APP_SENTRY_DSN,
-				release: packageJson.version,
-				integrations: [new Integrations.BrowserTracing()],
-				tracesSampleRate: 0.01,
-				beforeSend(event, hint) {
-					// Check if it is an exception, and if so, show the report dialog
-					if (event.exception) {
-						Sentry.showReportDialog({ eventId: event.event_id });
-					}
-					return event;
-				},
-			});
-		}

Google Maps

In order to display Google Maps Embed API in location messages, you need to provide a Google Maps API key in public/config.json for APP_GOOGLE_MAPS_API_KEY.

REACT_APP_TITLE: Application (page) title.

REACT_APP_MANIFEST_URL: manifest.json URL. This file provides information about the application.

REACT_APP_FAVICON_URL: Page favicon URL.

REACT_APP_LOGO_512_URL: 512x512 PNG icon used for mobile devices.

REACT_APP_LOGO_192_URL: 192x192 PNG icon used for mobile devices.

REACT_APP_LOGO_URL: Application logo URL.

REACT_APP_LOGO_BLACK_URL: Black and white version of application logo (used inside the loading screen).

To run it locally, just execute the following:

npm install
npm start

Dockerfile

First you need to create a Dockerfile on the root directory of the repository.

FROM nginx:stable-alpine
COPY build /usr/local/nginx/html

RUN rm /etc/nginx/conf.d/default.conf
COPY nginx.conf /etc/nginx/conf.d

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Nginx Configuration

You will need the following configuration for nginx.

server {
         listen 80  default_server;
         listen [::]:80;
         root /usr/local/nginx/html/;
         index index.html index.htm;
}

Build

You have to build the web-app with:

npm install
npm run build

It will create a build folder containing the webpage. And then build the Docker image with:

docker build -t web-app .

Run

To run, execute:

docker run -it -p 8080:80 web-app

The webpage will be available on http://localhost:8080

After changing the logo, this is the new look of the loading page:

A partner that wants to use its HubSpot app with the HubSpot plugin has to set up the following:

1. Inside the HubSpot application settings, go to Basic info >> Auth:
   

   1. Set the following Scopes from CRM:

   2. Enable the oauth option from Standard:

2. Go to CRM cards >> Create CRM card:

3. Set the Data fetch URL option to account-api.get.chat/proxy/packages/e62ba7adbd294ef18502d71c6bf456d2?path=/api/v1/plugins/public/webhook/&format=json&type=hubspot&webhook_type=readonly and set Target record types as follows:

4. Go to Card properties and add the following property:

5. Out of CRM cards, you go to Timeline events

   You need 2 of them:

   • Incoming Message Event
   • Outgoing Message Event

   1. Incoming Message Event

   2. Outgoing Message Event

   3. Both of them need the following custom tokens:

6. Finally, out of Timeline events go to Webhooks and create the following subscription:

A partner that is looking to deploy a HubSpot plugin for a customer should:

• Use this endpoint to start the integration with HubSpot: https://{inbox_domain}/activate_plugin/HubSpotIntegration
• Create a Stack

Use this endpoint to create a Stack for the organization you just created.

• Get list of packages

Use this endpoint to search for the unique ID for the get.chat inbox package.

• Deploy an inbox on that Stack

Use this endpoint to deploy the inbox package in the stack that you just created. Remember that you will be billed for every inbox that is deployed on the customer accounts that are linked to your partner account.

After successfully deploying the inbox package, the owner email address will receive an email with an activation link to start using the inbox. You are all set!

Where do I get the 360dialog API key from?

You can either ask the end user as they can retrieve it manually from their 360dialog HUB account, or you can use the 360dialog's Partner Connect button. The second option is much preferred for customers as they don't need to do anything and the conversion is way higher, but it's only available for React applications for now.

If you are still not a 360dialog partner you can join their partnership program here.