Links

Quick Start

Build Your First Integration

In this quick start tutorial, you'll:
👉 Server side
  1. 1.
    Initialise backend SDK with API key
  2. 2.
    Create a 'linked account id'
  3. 3.
    Generate 'session token' to be used on client side
  4. 4.
    Send an event to Cobalt (optional)
👉 Client side
  1. 1.
    Initialise frontend SDK with 'session token'
  2. 2.
    Get apps to list the enabled apps along with their status
  3. 3.
    Call connect() function to authenticate a new app

Prerequisites

  • Cobalt Account
  • API Key
How to find the API Keys on Cobalt's dashboard

Step 1: Initialise backend SDK with API key

Cobalt backend SDK documentation: https://www.npmjs.com/package/@cobaltio/cobalt
The preferred way to install the Cobalt backend SDK for Node.js is to use the npm package manager. Simply type the following into a terminal window:
npm i @cobaltio/cobalt
Once you have you api key, you can initialize the Cobalt Client by:
const Cobalt = require('@cobaltio/cobalt');
const Client = new Cobalt({
apiKey:"<Your Api Key>"
});

Step 2: Create a 'linked account id'

Linked Account is your end customer who will be using the integration. Cobalt will store all the end customer tokens against an unique linked account id provided by you. This API creates a Linked Account for the user for whose behalf you'd be calling the Cobalt APIs. The api expects linked_account_id as a mandatory field.
Field
Type
Details
linked_account_id
string
Mandatory. Unique id of the end customer
payload (optional)
object
In the object, you can set a name of the end customer
try {
await Client.createLinkedAccount({
linked_account_id:"<Linked Account Id>",
payload:{
name: "<Name for the account>",
}
}
})
} catch(error){
//Catch any error
}

Step 3: Generate 'session token' to be used on client side

While calling the Cobalt APIs from client side, you need to generate and use a session token, to avoid exposing API key on the client side. The API expects linked_account_id. You can call the API like:
try {
const session_token = await Client.getTokenForLinkedAccount({
linked_account_id:"<Linked Account Id>"
})
} catch(error) {
//Catch any error
}

Step 4: Send an event to Cobalt (optional)

App Events are custom events that are sent programmatically from your application via the SDK to trigger Workflows. For example, you might send a "New Contact Created" App Event from your application to trigger a Workflow that creates a matching contact in your users' Salesforce CRM.
Create an event on Cobalt
To create an event, go to the Your App page on Cobalt dashboard. Under the event tab click on 'New Event'. Next, enter the name and event schema of your Event. The event schema that you enter here must represent a sample payload sent from your application to Cobalt.
Create a new event create a new event on Cobalt
NOTE: The event schema must be a valid JSON object.
Send an event to Cobalt via SDK
App Events can be sent from your application to Cobalt using the event() function of the backend SDK. To trigger the event function, you must pass three parameters in the request:
Field
Type
Details
linked_account_id
string
Must be a unique string to identify an end-customer
event
string
Name of the event. Must be exactly same as mentioned on Cobalt's platform
payload
object
Must be in the same format as defined on the Cobalt's platform. You can create nested objects as well
config_id (optional)
string
Advanced concept of setting up individual configs from the frontend SDK. Refer to Config Fields for more details
Look at the below code to see a sample function call:
// Send the "New Contact Created" App Event
try{
const data = await Client.event({
linked_account_id:"<Linked Account Id>",
event: "New Contact Created",
config_id: "config1",
payload: {
"name": "Jeff Atwood",
"email": "[email protected]",
"phone": "4151231234",
"company": "Stack Overflow",
"role": "Founder"
}
})
}catch(error){
//Catch any error
}
You can check if the events are being fired in the 'Logs' tab on the Cobalt's platform
Event logs on Cobalt's Platform
🎉 Hurray! you have successfully integrated Cobalt on the server side. Now, let's look at the setup on client side.

Step 5: Initialise frontend SDK with 'session token'

Cobalt frontend SDK documentation: https://github.com/gocobalt/cobalt-js#cobaltjs
The preferred way to install the Cobalt frontend SDK for javascript is to use the npm package manager. Simply type the following into a terminal window:
npm install @cobaltio/cobalt-js
Alternatively, you can also install the frontend SDK on the browser using the script tag
<!-- use a specific version -->
<script src="https://cdn.jsdelivr.net/npm/@cobaltio/[email protected]"></script>
<!-- use a version range instead of a specific version -->
<script src="https://cdn.jsdelivr.net/npm/@cobaltio/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/@cobaltio/[email protected]"></script>
<!-- omit the version completely to use the latest one -->
<!-- you should NOT use this in production -->
<script src="https://cdn.jsdelivr.net/npm/@cobaltio/cobalt-js"></script>
Initializing the javascript SDK using session token
const cobalt = new Cobalt({
// the token you generate for linked accounts using the cobalt backend SDK
token: "COBALT_SESSION_TOKEN",
});
The session token gets expired in 24 hours. Please make sure you generate a new token in every new session or within 24 hours.

Step 6: Get apps to list the enabled apps along with their status

cobalt.getApp(slug) ⇒ Promise
Use the getApp() function to list status of all apps or a particular app. If the 'slug' is empty, it will return an array of objects containing all the application. 'Slug' is a unique identifier for each application on Cobalt. For eg. if you pass slug='slack', you will get details only pertaining to slack.
cobalt.getApp('slug');
Response of getApp() function will be an array of object. You can use the [connected] field inside the object to show the application connection status to an end customer. The 'Application' object will have the following list of fields:
Name
Type
Description
name
String
name of the application
description
String
description of the application
icon
String
URL of icon of the application
typed
String
application slug of native apps
[slug]
String
application slug of custom apps
auth_type
"oauth2" | "keybased"
The type of auth used by application
[connected]
Boolean
Whether the user has connected the application.
[auth_input_map]
Array.<InputField>
The fields required from the user to connect the application (for keybased auth type).
Let's look at a sample response of .getApp() function
//response of getApp() function returning the two enabled apps
[
{
"name": "Slack",
"icon": "https://cobalt-app-logos.s3.ap-south-1.amazonaws.com/slack/logo.png",
"description": "Slack is a platform for team communication: everything in one place, instantly searchable, available wherever you go. Offering instant messaging, document sharing and knowledge search for modern teams.",
"auth_type": "oauth",
"type": "slack",
"app_id": "63e61631085cbdc8837b1ed7",
"version": {
"_v": "1.0.0",
"description": "Slack is a platform for team communication: everything in one place, instantly searchable, available wherever you go. Offering instant messaging, document sharing and knowledge search for modern teams."
},
"connected": true,
"connected_accounts": [
{
"identifier": "Cobalt",
"connectedAt": "2023-05-03T12:08:08.321Z"
}
]
},
{
"name": "Active Campaign",
"icon": "https://cobalt-app-logos.s3.ap-south-1.amazonaws.com/activecampaign/logo.png",
"description": "Customer experience automation (CXA) platform that helps businesses meaningfully engage customers. Access pre-built automations that combine transactional email and email marketing, marketing automation, ecommerce marketing, and CRM for powerful segmentation and personalization across social, email, messaging, chat, and text.",
"auth_type": "key_url",
"type": "activecampaign",
"app_id": "63e61631085cbdc8837b1ee3",
"auth_input_map": [
{
"name": "access_token",
"type": "text",
"required": true,
"variable": false,
"multiple": false,
"placeholder": "Please Enter access token",
"label": "ACCESS TOKEN"
},
{
"name": "base_url",
"type": "text",
"required": true,
"variable": false,
"multiple": false,
"placeholder": "Please Enter base url",
"label": "BASE URL"
}
],
"version": {
"_v": "1.0.0",
"description": "Customer experience automation (CXA) platform that helps businesses meaningfully engage customers. Access pre-built automations that combine transactional email and email marketing, marketing automation, ecommerce marketing, and CRM for powerful segmentation and personalization across social, email, messaging, chat, and text."
}
}
]
You can show a list of apps on your client side based on above response from .getApp() function when you send an empty value in slug. See below example:
Sample list of integrations on your client side

Step 7: Call .connect() function to authenticate a new app

cobalt.connect(slug, [payload]) ⇒ Promise.
Connect the specified application, optionally with the auth data that user provides. Kind: instance method of Cobalt Returns: Promise. - Whether the connection was successful.
Param
Type
Default
Description
slug
String
The application slug.
[payload]
Object.<string, (string|number|boolean)>
{}
The key value pairs of auth data. You can find this in [auth_input_map] field in response of getApp
//OAuth based authentication
cobalt.connect('slack');
////Key based authentication
cobalt.connect('activecampaign',{"access_token":"ttkpkasxmc090123knvgj324bjkasuwqwub", "base_url":"https://<your-account>.api-us1.com/api/3/<resource>"});
For OAuth, the connect button will take the user to a separate page and the request will be handled by Cobalt. For key-based authentication, you can build a custom modal based on the 'auth-input-map' field of getApp() function. See sample below:
Sample modal for key-based authentication on client side:

Step 8 (optional): Use .disconnect() to remove a connected app

cobalt.disconnect(slug) ⇒ Promise
Disconnect the specified application and remove any associated data from Cobalt.
cobalt.disconnect('slack');
🎉 Hurray! you have successfully integrated Cobalt on the client side and enabled your first integration