Introduction

Overview

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

Use cases

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

  • build a custom chat widget
  • interact with a chat as a customer (join a chat, post messages)

This API is used in chat.io chat widget.

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 Agent 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 Customer 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 push incoming_multicast

Changed

  • last_event_per_type object is now map of objects with specific type of event, thread_order and thread_id
  • last_event_per_type object contains last events from chat instead of thread

Fixed

  • Support for file event in last_event_per_type for non-active chats

[v0.3] - 2017-11-09

Added

  • New method get_chats_summary
  • New reasons in customer_disconnected push
  • Short guide for RTM API and Web API to docs
  • Total events to threads_summary object

Changed

  • Require customer to authorize with token param instead of cookies in login request
  • Expect offset and limit params instead of pagination object in get_chat_threads_summary request
  • Always use offset for pagination instead of page
  • Return total results rather than pagination object
  • Replace properties with fields in customer object
  • Update error handling
  • Every validation error has user-friendly message with details

Removed

  • last_chats_limit and last_threads_limit params from login request
  • Customer’s chats in login response

Fixed

  • author_id in custom event

[v0.2] - 2017-09-01

Added

  • Support for chat scopes
  • New chat event type - custom

Changed

  • Pushes with empty list of updated properties will no longer be sent

Removed

  • Method send_message in RTM API

[v0.1] - 2017-04-24

:sparkles:

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.