Quick Start
To authorize, use this code:
import Chat from 'chatinc';
const API_KEY = 'API_KEY';
const chat = new Chat(API_KEY);
A campaign consists of the message to be sent to a select audience based on a set of criteria. You can specify the message to be sent, include interactive buttons, and personalise using variables. In addition you can specify time to send. If you set the runImmediately parameter to false when creating the campaign it will instead of sending the message create a WhatsApp Template message that can be used in a future campaign. Lastly, you can retrieve the results of each campaign.
The process of creating and sending a campaign should be done using the following sequence:
- Create your audience,
- Create your VariableGroup with Variables
- Create your campaign and then Lastly,
- Run your campaign
Run npm install chatinc
Available Libraries
JS Library available on npm.
Campaigns
Campaigns are how you send broadcast campaigns to your audience. Use the Campaigns API calls to manage campaigns in your Chat Inc account.
Create Campaign
Use this endpoint to create a campaign
chat
.createCampaign(
{
title: "My Marketing Campaign",
message: "This is an awesome broadcast campaign message.",
buttons: [
{
text: "Button 1",
type: "journey",
journeyId: "myJourneyId",
},
],
},
{
runImmediately: true,
audiences: ["Frequent Shoppers"],
}
)
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
Create a new campaign.
POST https://api.chatinc.com/v1/create/campaign
Post Parameters
| Parameter | Required | Description |
|---|---|---|
| title | yes | This is the name of the campaign. You will be able to identify your campaign by the title you give it. |
| message | yes | This will be the display text that users read from your campaign. You can specifiy where variables will be placed through the {variable_group_name.variable_name} syntax. See the Messages with Variables section to learn more about variables. |
| imgUrl | optional | An image for your campaign |
| options.whatsAppTemplateType | optional | Defaults to MARKETING if not specified. Available types MARKETING |
| buttons | reccommended | Buttons are the actions your users will take after receiving your campaign message. Buttons is an Array with, for example, {text:"Hello", "type":"journey","journeyId:"journeyId"} objects. The journeyId is created from the builder. See the builder api section to learn more about creating journeys and retrieving journey IDS. You can also create button of type phone, url or input. See the Buttons section to learn more about buttons. |
| options.runImmediately | optional | If set to true the campaign will be sent immediately. Defaults to false if not specified. |
| options.audiences | optional | An array of audiences that you want to target with your campaign. Use the id all. See the Contacts API section to learn more about creating audiences and retrieving audience tags. |
| options.languageCode | optional | The language code of the campaign. Defaults to enUS if not specified. |
| options.timeToRun | optional | Unix timestamp of the time you want the campaign to run. If not specified, the campaign will run immediately. |
Add Buttons
Buttons are interactive and can be used to collect structured text responses or link to a website or phone number. There are 4 types of buttons you can create for your campaign. They are a form of structured input that allows your audience to press a button instead of having to type, thereby eliminating typing errors.
Input Buttons
{
text: "Send Message",
type: "input",
input: "Hello, World."
}
Are used to collect inputs or responses from users by converting a button press into a structured text input which is either saved to an InputGroup or used to trigger other interactive journeys. The InputGroup is the storage for all inputs or responses collected from your audience, and has the same name as your campaign.
Journey Buttons (Beta)
{
text: "Start",
type: "journey",
journeyId: "myJourneyId"
}
Are used to direct your audience to an interactive journey. A journey is a series of interactive messages that you create using the Journey Builder API.
Phone Buttons
{
text: "Call Us",
type: "phone",
phoneNumber: "+1234567890"
}
Are buttons that allow your users to call a phone number. Phone buttons can only be used together with URL buttons and vice versa, and cannot be combined with Input or Journey Buttons.
URL Buttons
{
text: "Visit Site",
type: "url",
url: "https://www.google.com"
}
Are buttons that allow your users to visit a URL. These can be either static such as a website, landing page or dynamic like unique payment links.
Create Variables
Variables are used to personalise your campaign messages to your audience. You add variables by first specifying a VariableGroup, which is the place where related variables reside. For example, if you want to send a message to a user that says:
"Hello, John Doe. How are you today?"
You would create a VariableGroup named users and add two variables to it, first_name and last_name. You would then use the variable group in your message like so: Hello, {users.first_name} {users.last_name}. You can now redeem your exclusive offers store?
Create Variable Group
Use this endpoint to create a variable group
chat.createVariableGroup({
id: 'myVariableGroupId',
name: 'My Variable Group',
description: 'This is my variable group',
fields: ["first_name", "last_name"]
values: [{
number: '1234567890',
first_name: "John",
last_name: "Doe"
}]
}).then((response) => {
console.log(response);
}).catch((error) => {
console.log(error);
});
Can be created using the below endpoint. Note that VariableGroups can also be created automatically as a result of creating input groups. When you create a variable group from a csv file you can also automatically create an audience along with it. To do this, simply add the audienceId parameter to the request.
HTTPS Request
POST http://api.chatinc.com/v1/create/variable/group
Create Variable Group from CSV File
Use this endpoint to create a variable group from a CSV file
//This feature is only possible using a REST API Call. See Shell implementatiom
Multipart POST Request
POST http://api.chatinc.com/v1/create/variable/group/from/file
Parameters
| Parameter | Required | Description |
|---|---|---|
| file | yes | The CSV file you want to upload |
| name | yes | The name of the variable group |
| id | yes | The id of the variable group |
| audienceId | yes | The audience you want to add the variable group to |
Retrieve Variable Groups
Use this endpoint to retrieve all your variable groups
chat
.retrieveVariableGroups()
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
The above endpoint returns an object structured as below:
[
{
"name": "users",
"fields": ["first_name", "last_name"]
}
]
When you retrieve variable groups you will get an array of objects. Each object will have a name and fields property. The name property is the name of the variable group. The fields property is an array of the variables in the variable group.
You will also receive variable groups that have been created as a result of creating input groups.
Create Audience
Audiences are how you segment your contacts into groups. You create audiences based on user/customer attributes, such as location, or based on user/customer behaviour, such as whether they have purchased from you before. You use audiences to send campaigns to specific groups of contacts (customers, users, people, other).
Create Audience
Use this endpoint to create an audience
chat
.createAudience({
id: "myAudienceId",
name: "My Audience",
description: "This is my audience",
contacts: [
{
number: "1234567890",
},
],
})
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
HTTPS Request
POST http://api.chatinc.com/v1/create/audience
Add Contacts to Audience
Use this endpoint to add contacts to an audience
chat
.addContactsToAudience({
id: "myAudienceId",
contacts: [
{
number: "1234567890",
},
],
})
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
HTTPS Request
POST http://api.chatinc.com/v1/create/audience
Add Contacts to Audience from CSV File
Use this endpoint to add contacts to an audience from a CSV file
//This feature is only possible using a REST API Call. See Shell implementatiom
Multipart POST Request
POST http://api.chatinc.com/v1/create/audience/from/file
Parameters
| Parameter | Required | Description |
|---|---|---|
| file | yes | The CSV file you want to upload |
| name | yes | The name of the audience |
| id | yes | The id of the audience |
Retrieve Audiences
Use this endpoint to retrieve all your audiences
chat
.retrieveAudiences()
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
HTTPS Request
GET http://api.chatinc.com/v1/retrieve/audiences
Retrieve Audience Contacts
Use this endpoint to retrieve details about a particular audience
chat
.retrieveAudienceCotacts({
id: "myAudienceId",
})
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
HTTPS Request
POST http://api.chatinc.com/v1/retrieve/audience/contacts
Send Campaign
Use this endpoint to create a campaign
chat
.runCampaign({
campaignId: "myCampaignId",
audiences: ["all"],
})
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
POST https://api.chatinc.com/v1/run/campaign
This endpoint allows you to run a campaign that has previously been created using the runImmediately parameter set to false. Alternatively you can resend a previously sent campaign using its campaignID.
Post Parameters
| Parameter | Required | Description |
|---|---|---|
| campaignId | yes | The ID of the campaign you want to run. You can retrieve the campaign ID from the Campaigns API |
| audiences | yes | An array of audiences, specified by audienceIds, that you want to target with your campaign. If you wish to target all your contacts use the id all. See the Contacts API section to learn more about creating audiences and retrieving audience Ids |
| timeToRun | optional | The time you want to run the campaign. This is a UNIX timestamp. If you don't specify a time, the campaign will be run immediately. |
Campaign Results
Retrieve campaign results such as Sent, Delivered, Read, SendErrors, DeliveryErrors, NumbersNotOnWhatsApp, Read rate, and Delivery rates.
Retrieve All Campaigns
Use this endpoint to retrieve all your campaigns
chat
.retrieveCampaigns()
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
The above endpoint returns an object structured as below:
[
{
"status": "success",
"campaigns": {
"imgUrl": "https://storage.googleapis.com/otarkie-pay-dev.appspot.com/bots/files/WhatsApp Image 2023-05-18 at 09.56.00.jpeg.jpeg",
"variables": [],
"buttons": [
{
"text": "Complete Application",
"type": "input"
}
],
"campaignId": "chatstack_agfobasx",
"locale": "en_US",
"message": "Hi!👋 Excited to try out campaigns",
"templateId": "chatstack_agfobasx",
"title": "test_with_image",
"runs": [],
"totalSent": 0,
"totalDelivered": 0,
"totalRead": 0,
"whatsAppTemplatesStatus": "APPROVED"
}
}
]
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| active | optional | If set to true the endpoint only retrieves active campaigns |
HTTPS Request
POST https://api.chatinc.com/v1/retrieve/campaigns
Retrieving Campaign Details
Use this endpoint to retrieve details about a particular campaign
chat
.retrieveCampaignDetails({
campaignId: "myCampaignId",
})
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
The above code returs a JSON objecta structured as follows:
[
{
"number":"",
"action":"",
...
}
]
You can specify whether or not you wish to receive the campaign details in csv format of which you will receive all the results.
HTTPS Request
POST https://api.chatinc.com/v1/retrieve/campaign
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| campaignId | yes | The ID of the campaign |
| format | optional | csv or json |