Quick Start

To authorize, use this code:

import Chat from 'chatinc';

const API_KEY = 'API_KEY';
const chat = new Chat(API_KEY);

# With shell, you can just pass the correct header with each request
curl "https://api.chatinc.com/end_point"
  -H "Authorization: [Your 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);
  });

curl --request POST \
  --url https://api.chatinc.com/v1/create/campaign \
  --header 'Authorization: [API Key]' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "campaign title",
    "templateType": "MARKETING",
    "message": "My message {}",
    "imgUrl": "my-imageurl",
    "buttons": [
        {
            "text": "Start",
      "type" : "journey",
            "journeyId": "myJourneyID"
        },
    {
      "text": "Vist site",
      "type" : "url",
      "url": "https://www.google.com"
    }
    ],
}'

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."
}

{
  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"
}

{
  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"
}

{
  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"
}

{
  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


curl --request POST \
  --url https://api.broadcast.chatinc.com/v1/create/variable/group/from/file \
  --header 'Authorization: [API Key]' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@/Users/user/Downloads/TFG June Invite - File Drop 2 Variables.xlsx - Sheet1.csv' \
  --form name=large_group_10k_2 \
  --form id=large_group_10k_2 \
  --form audienceId=30k

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);
  });


curl --request POST \
  --url https://api.chatinc.com/v1/retrieve/variable/groups \
  --header 'Authorization: [API Key]' \
  --header 'Content-Type: application/json' \

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

curl --request POST \
  --url https://api.broadcast.chatinc.com/v1/create/audience/from/file \
  --header 'Authorization: [API Key]' \
  --header 'Content-Type: multipart/form-data' \
  --form name=testos \
  --form id=testos \
  --form 'file=@/Users/user/Library/Mobile Documents/com~apple~CloudDocs/TFG (2000) Variable Group Values Upload.xlsx - Sheet1.csv'

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);
  });

curl --request POST \
  --url https://api.chatinc.com/v1/create/campaign \
  --header 'Authorization: [API Key]' \
  --header 'Content-Type: application/json' \
  --data '{ "campaignId": "myCampaignId" }'

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);
  });


curl --request GET \
  --url https://api.broadcast.chatinc.com/v1/retrieve/campaigns \
  --header 'Authorization: [API Key]'

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);
  });


curl --request POST \
  --url https://api.broadcast.chatinc.com/v1/retrieve/campaign \
  --header 'Authorization: [API Key]' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignId":"c_B5ibuY0ubsjsGHE",
  "format":"csv"
}'

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