How to set up an API channel?

In this article, you will learn the following information:

• How to set up an API channel?
• How to send a message through the API channel?
  • Creating a contact
  • Creating a conversation
  • Creating a message
• Additional channel settings
  • "Settings" section
  • "Collaborators" section
  • "Business hours" section
  • "CSAT" section
  • "Configuration" section

---

 

How to set up an API channel?

 

To create and configure an inbound API channel, go to Settings → Inboxes → Add Inbox.

 

 

Select API.

 

 

Specify the channel name and the webhook URL where you wish to receive callback events. Click Create API Channel.

 

 

Add agents to your API channel.

 

 

You have successfully created an API inbox.

 

---

 

How to send a message through the API channel?

 

To send a message through the API, create a contact, initiate a conversation, and then send the message.

API requests require an api_access_token in the request header. To obtain this token, contact the BrandWizard manager.

 

---

 

Creating a contact

 

To create a contact, send the API source ID along with other specified parameters. This will automatically generate a request. The response will look like this:

 

{
  "email": "string",
  "name": "string",
  "phone_number": "string",
  "thumbnail": "string",
  "additional_attributes": {},
  "contact_inboxes": [
    {
      "source_id": "string",
      "inbox": {
        "id": 0,
        "name": "string",
        "website_url": "string",
        "channel_type": "string",
        "avatar_url": "string",
        "widget_color": "string",
        "website_token": "string",
        "enable_auto_assignment": true,
        "web_widget_script": "string",
        "welcome_title": "string",
        "welcome_tagline": "string",
        "greeting_enabled": true,
        "greeting_message": "string"
      }
    }
  ],
  "id": 0,
  "availability_status": "string"
}

 

As shown, in the response you will see contact_inboxes, and each will have its own source_id. The source_id can be considered as the request identifier. You will use this source_id to create a new conversation, as described below.

 

---

 

Creating a conversation

 

Use the source_id obtained in the previous step. You will receive a conversation_id, which can be used to create a message.

 

{
  "id": 0
}

 

---

 

Creating a message

 

There are two types of messages:

• Incoming: a message from the user.
• Outgoing: a message from the agent.

An example response upon successful sending:

 

{
    "id": 0,
    "content": "This is an incoming message via API channel",
    "inbox_id": 0,
    "conversation_id": 0,
    "message_type": 0,
    "content_type": null,
    "content_attributes": {},
    "created_at": 0,
    "private": false,
    "sender": {
        "id": 0,
        "name": "Pranav",
        "type": "contact"
    }
}

 

If everything is successful, you will see the conversation in the conversation management panel, and you will also be notified about new messages via the URL provided when creating the API channel.

 

---

 

Additional channel settings

 

The created API channel should appear in the list under Inboxes. To view or change additional settings, go to Settings → Inboxes, then click the gear icon on the API channel.

 

 

You will see the following page:

 

 

---

 

"Settings" section

 

• Channel Avatar. Add an image of the inbox.
• Inbox Name. Change the inbox name if needed.
• Webhook URL. If necessary, change the webhook URL.
• Enable channel greeting. After activation, BrandWi will send a welcome message for new conversations created via your API channel.
• Channel greeting message. This field appears if you enable the channel greeting. Write a response that the client will see after sending their first message, e.g., "BrandWizard usually responds within a few minutes."

After making changes, click Update.

 

 

---

 

"Collaborators" section

 

Click on the Collaborators tab. Here you can add or remove agents from the channel. You can also enable or disable automatic assignment of new conversations to agents added to this inbox. If needed, limit the maximum number of conversations from the inbox that can be automatically assigned to an agent. Click Update to save changes.

 

 

---

 

"Business hours" section

 

Go to the Business hours tab. In this section, you can set your team's working hours related to the API channel. To activate the working hours mode, check the Enable business availability for this inbox.

• Once checked, you'll be able to write a message for clients to see during non-working hours.
• You can also set working hours for each day of the week, considering the selected time zone.

After adjusting the settings, click the Update business hours settings button.

 

 

---

 

"CSAT" section