REST API Reference (V1)
Team
Base
Check If Team ExistsheadCreate TeampostGet A TeamgetDelete A Teamdelete
Conversations
⭐ List Conversationsget

REST API Reference (V1)

Updated on December 22, 2021

The Acme REST API offers access and control over all Acme data.

All resources that you will most likely use are prefixed with a star symbol (⭐).

While integrating the REST API, you may be interested in the following guides:

Basein Team

Check If Team Exists

HEAD
/v1/team{?domain}

Checks if given team exists (by domain).

URI Parameters
domain
stringRequired

The team domain to check against

  • HEADhttps://api.acme.com/v1/team
  • Tiersuserapp
HTTP
Request
(loading)
Response
(loading)

Create Team

POST
/v1/team

Creates a new team.

Request Body
name
stringRequired

Team name

domain
stringRequired

Team domain

  • POSThttps://api.acme.com/v1/team
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Get A Team

GET
/v1/team/{team_id}

Resolves an existing team information.

URI Parameters
team_id
stringRequired

The team identifier

Response Data
error
boolean
reason
string
data
object
team_id
string

Team identifier

name
string

Team name

domain
string

Team domain

  • GEThttps://api.acme.com/v1/team/team_id
  • Tiersuserapp
HTTP
Request
(loading)
Response
(loading)

Delete A Team

DELETE
/v1/team/{team_id}

Deletes an existing team.

URI Parameters
team_id
stringRequired

The team identifier

Request Body
verify
stringRequired

User password (used to double-authenticate deletion)

  • DELETEhttps://api.acme.com/v1/team/team_id
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Conversationsin Team

⭐ List Conversations

GET
/v1/team/{team_id}/conversations/{page_number}{?search_query}{&search_type}{&search_operator}

Lists conversations for team.

URI Parameters
team_id
stringRequired

The team identifier

page_number
stringOptional

Page number for conversations paging

search_query
stringOptional

Search query in all conversations (text if type is text or segment, filter if type is filter)

search_type
stringOptional

Search type (either text, segment or filter)

search_operator
stringOptional

Search operator if search type is filter (or or and respectful to boolean algebra, defaults to and if not set)

Response Data
error
boolean
reason
string
data
array[object]
session_id
string

Session identifier

team_id
string

Team identifier

people_id
string

People identifier

state
enum[string]

Conversation state

Values

  • pending
  • unresolved
  • resolved
status
enum[number]

Conversation status (an alias of state; useful for sorting conversations)

Values

  • 1
  • 2
is_verified
boolean

Whether session is verified or not (user email ownership is authenticated)

is_blocked
boolean

Whether session is blocked or not (block messages from visitor)

availability
enum[string]

Visitor availability

Values

  • online
  • offline
active
object

User activity statistics

now
boolean

Whether user is considered active right now or not

last
number

Timestamp at which the user was last active

last_message
string

Last message excerpt

participants
array[object]

External participants for this conversation

type
enum[string]

External participant type

Values

  • email
target
string

External participant target (ie. email address, identifier, etc.)

mentions
array[string]

Mentioned user identifiers (from conversation messages)

created_at
number

Conversation creation timestamp

updated_at
number

Conversation update timestamp

compose
object

Compose states

operator
object

Compose state for operator

type
enum[string]

Compose state type

Values

  • start
  • stop
excerpt
string

Message excerpt for compose state

timestamp
number

Timestamp for compose state

user
object

Compose user information

user_id
string

Compose user identifier

nickname
string

Compose user nickname

avatar
string

Compose user avatar

visitor
object

Compose state for visitor

type
enum[string]

Compose state type

Values

  • start
  • stop
excerpt
string

Message excerpt for compose state

timestamp
number

Timestamp for compose state

unread
object

Unread messages counters

operator
number

Unread messages counter for operator

visitor
number

Unread messages counter for visitor

assigned
object

Assigned operator (if any)

user_id
string

Operator user identifier

meta
object

Meta-data for conversation

nickname
string

Visitor nickname

email
string

Visitor email

phone
string

Visitor phone

address
string

Visitor address

ip
string

Visitor IP address

data
object

Visitor data

avatar
string

Visitor avatar

device
object

Device information

capabilities
array[enum[string]]

Visitor device capabilities

Values

  • browsing
  • call
geolocation
object

Geolocation information for visitor device

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

system
object

Visitor device system information

os
object

Operating system information

version
string

OS version

name
string

OS name

engine
object

Rendering engine information

version
string

Engine version

name
string

Engine name

browser
object

Browser information

major
string

Browser major version (eg: version 8.1 has a major of 8)

version
string

Browser version

name
string

Browser name

useragent
string

Visitor user agent

timezone
number

Visitor device timezone offset (UTC)

locales
array[string]

Visitor device locales

segments
array[string]

Segments attributed to conversation

  • GEThttps://api.acme.com/v1/team/team_id/conversations/page_number
  • Tiersuserapp
  • Scopesteam:conversation:sessions
HTTP
Request
(loading)
Response
(loading)