Quick Start
In this quick start tutorial, you'll:
👉 Server side
- 1.Initialise backend SDK with API key
- 2.Create a 'linked account id'
- 3.Generate 'session token' to be used on client side
- 4.Send an event to Cobalt (optional)
👉 Client side
- 1.Initialise frontend SDK with 'session token'
- 2.Get apps to list the enabled apps along with their status
- 3.Call connect() function to authenticate a new app
- Cobalt Account
- API Key
How to find the API Keys on Cobalt's dashboard
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>"
});
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
}
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
}
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.
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.
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
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:
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
Last modified 10d ago