Introduction

Overview

Chat.io Agent API allows you to join a chat as an agent. It has a different set of methods than the Customer API. The main reason to have separate APIs for both Customer and Agent are their specific use cases.

Use cases

With chat.io Agent API you can do the following:

  • build a custom Agent App
  • interact with a chat as an agent (join a chat, post messages)
  • browse chat archives
  • ban customers

This API is used in chat.io Agent App.

Important notes

To use this tool you need to have basic knowledge of REST or websocket APIs, OAuth 2.0 protocol and your technology of choice. We’ve got examples ready in JavaScript, Go and Python.

If you want to perform a chat from the customer perspective, you should use Customer API.

This API is under heavy development. We introduce changes every month. If you want to stay updated, follow the changelog below.

Getting started

Prerequisites

To start off with chat.io Agent API, follow these steps:

  1. Sign up or sign in to the Developers Console.
  2. Create a new app (“Backend” type).
  3. Copy the Client Secret and Client ID.

Changelog

[v0.5] - 2018-01-12

Added

  • New chat event type - rich_message
  • New method: send_rich_message_postback and push: incoming_rich_message_postback

[v0.4] - 2017-12-04

Added

  • New method multicast
  • in_trial to license object in login response

Changed

  • Push message incoming_broadcast changed to incoming_multicast
  • last_event_per_type object is now a map of objects with a specific type of event, thread_order and thread_id
  • last_event_per_type object contains the last events from a chat instead of a thread

Removed

  • Method send_broadcast, use multicast instead

Fixed

  • Support for file event in last_event_per_type for non-active chats
  • Include different types of events in last_event_per_type for non-active chats

[v0.3] - 2017-11-09

Added

  • Support for uploading images
  • Support for sending messages as bots with author_id
  • creation_date to license object in login response

Changed

  • Replace properties with fields in customer object
  • Every validation error has user-friendly message with details

Removed

  • Method send_message, use send_event instead
  • Method supervise_chat as well as supervisor/supervisors objects

Fixed

  • author_id in custom event

[v0.2] - 2017-09-01

Added

  • monitoring to customer object in get_archives response
  • Support for chat scopes
  • Support for managing auto chat scopes configuration
  • Support for sending broadcast to agents
  • New chat event type - custom

Changed

  • Move license_id and plan to license object in login response

Removed

  • Active chats from login response
  • firebase_token param from login request

[v0.1] - 2017-04-24

  • First release

Versioning

All components of this API have a single common version. This document describes its format and provides other related information.

Format

v<major>.<minor>

examples: v0.3 v0.4

Endpoints

Our components have different endpoints for every version. For example, here is what a URL with a version looks like for the Customer API:

api.chat.io/customer/v0.4/<req>

If you prefer to always point to the most recent version of the API (not recommended), use this:

api.chat.io/customer/<req>

Change policy

Before we reach the v1.0 version, new versions may introduce breaking changes. We don’t know yet if that policy holds after v1.0. We support old versions for an undefined period of time until v1.0. We will add a notice in this documentation that a version is deprecated before it’s removed.