CitNOW Conversations API Reference

API Endpoint

https://api.web1on1.chat/v2

Authentication ¶

All API requests are made on behalf of a registered User. An API request should always include the Authorization: Bearer _token_ header in the request HTTP headers list.

Example of valid API requests using cURL utility:

$ curl -H "Authorization: Bearer 94c70d470e391bdc16a8d8363b5d4891" \
       https://api.web1on1.chat/v2/path/to/resource

API tokens that are tied to a user with role “bot” do not expire, but may be revoked. The API key has the permissions of the associated user, and actions appear as if they were that user. If the associated user has its permissions changed, such as being removed from an organization, then the functionality of the key will change.

We recommend that different systems have different API tokens (bot users) for security purposes.

Time-based Tokens ¶

Web1on1 supports time-based tokens that expire after a set amount of time. These tokens are tied to the user session, and used primarily in our applications.

POST https://api.web1on1.chat/v2/auth/token

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "email": "jeff@jeffdoe.com",
  "password": "z3krut",
  "otp": "123456"
}

Responses201

Headers

Content-Type: application/json

Body

{
  "tokenType": "Bearer",
  "token": "eyK8eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1NDUwMDBlNTZkYWU2NzQxMTVjZWYyN2MiLCJpYXQiOjE0MTc0NjQzNDksImV4cCI6MTQxNzQ4MjM0OX0._ihtI_m5vf53m_qF0y_m-y_5X9Hy8Ik2A5qUTSkgNhA",
  "refreshToken": "eyK8eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1NDUwMDBlNTZkYWU2NzQxMTVjZWYyN2MiLCJpYXQiOjE0MTc0NjQzNDksImV4cCI6MTQxNzQ4MjM0OX0._ihtI_m5vf53m_qF0y_m-y_5X9Hy8Ik2A5qUTSkgNhA",
  "user": "599e1fcd9da1c72645c95886",
  "organization": "57c8479433f5d57d3013a0bc",
  "expiresAt": "2016-01-07T14:03:43Z",
  "scope": "admin"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tokenType": {
      "type": "string",
      "description": "Token type."
    },
    "token": {
      "type": "string",
      "description": "Authentication token. Expires after 24h."
    },
    "refreshToken": {
      "type": "string",
      "description": "Authentication token for refresh authentication. Expires after 1 month."
    },
    "user": {
      "type": "string",
      "description": "The ID of the User authenticated."
    },
    "organization": {
      "type": "string",
      "description": "Authenticated user organization ID."
    },
    "expiresAt": {
      "type": "string",
      "description": "ISO8601 date ant ime when token expires."
    },
    "scope": {
      "type": "string",
      "description": "Authenticated user scope."
    }
  }
}

Create an Access Token
POST`/auth/token`

To obtain an access token, make a POST request to https://api.web1on1.chat/v2/auth/token. The users’s email and password must be used in a JSON object posted to the token API URL.

The token expires after 24 hours; use the refresh token flow before expiration. After expiration a new token should be generated.

GET https://api.web1on1.chat/v2/auth/token?refreshToken

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "tokenType": "Bearer",
  "token": "eyK8eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1NDUwMDBlNTZkYWU2NzQxMTVjZWYyN2MiLCJpYXQiOjE0MTc0NjQzNDksImV4cCI6MTQxNzQ4MjM0OX0._ihtI_m5vf53m_qF0y_m-y_5X9Hy8Ik2A5qUTSkgNhA",
  "refreshToken": "eyK8eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1NDUwMDBlNTZkYWU2NzQxMTVjZWYyN2MiLCJpYXQiOjE0MTc0NjQzNDksImV4cCI6MTQxNzQ4MjM0OX0._ihtI_m5vf53m_qF0y_m-y_5X9Hy8Ik2A5qUTSkgNhA",
  "user": "599e1fcd9da1c72645c95886",
  "organization": "57c8479433f5d57d3013a0bc",
  "expiresAt": "2016-01-07T14:03:43Z",
  "scope": "admin"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tokenType": {
      "type": "string",
      "description": "Token type."
    },
    "token": {
      "type": "string",
      "description": "Authentication token. Expires after 24h."
    },
    "refreshToken": {
      "type": "string",
      "description": "Authentication token for refresh authentication. Expires after 1 month."
    },
    "user": {
      "type": "string",
      "description": "The ID of the User authenticated."
    },
    "organization": {
      "type": "string",
      "description": "Authenticated user organization ID."
    },
    "expiresAt": {
      "type": "string",
      "description": "ISO8601 date ant ime when token expires."
    },
    "scope": {
      "type": "string",
      "description": "Authenticated user scope."
    }
  }
}

Refresh an Access Token
GET`/auth/token?{refreshToken}`

Use the refresh token to request a new access token prior to expiration.

URI Parameters

HideShow

refreshToken: string (required)
Refresh token.

Messaging ¶

Conversations ¶

A conversation lets you track and describe communications with your users. To start a conversation you and your users can send messages; when the first message is received from a new Contact, a conversation is automatically created.

A conversation may have the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the Conversation.	56467a06d9b082b0059151dc
slug	string	Slug for the conversation for use in short URL path segments.	Byxu3buKiW
url	string	Viewer URL.	https://skynet.chat.report/c/Byxu3buKiW
organization	string	Organization ID, conversation owner.	58bcbafb8547f04f68c14bdb
name	string	Name for the conversation.	Bonbowack Acerfuse
type	enum	Conversation initiator type One of bot, contact, viewer, agent, admin, system. Defaults to bot.	bot
status	enum	Conversation status One of queued, active, closed. Defaults to queued.	queued
category	string	Category name.	Used Car
categoryIndex	number	Index of the category in the organization’s category list.	0
language	string	Conversation language.	en
contact	string	Contact ID of the visitor.	58bc9aecd906223dcec36493
messages	array	An array of Message IDs for this conversation.	[58bcbafb8547f04f68c14bdb]
meta	MetaParams	Free-form object of key-value pairs, representing context from the automation that created this conversation.	{MetaParams}
participants	array	An array of conversation participants.	[{Participant}]
channels	array	An array of Channel IDs that were notified for this conversation.	[56467a06d9b082b0059151dc]
channelsOffline	array	An array of Channel IDs that were not notified due to unavailability of agents.	[58bcbafb8547f04f68c14bdb]
touchpoints	Touchpoints	Touchpoints object representing consumer channels.	{Touchpoints}
forms	array	An array of incomplete or unsent forms.	[{ConversationForm}]
results	array	An array of completed and sent forms.	[{ConversationResult}]
createdBy	string	User ID of the user that created the conversation.	58bc9aecd906223dcec36495
createdAt	string	ISO8601 date and time when the Conversation was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time when the Conversation was last modified.	2016-01-07T14:03:43Z

conversation.participants

Over the course of a conversation, users that have joined or left the conversation are tracked in the participants attribute. It has the following structure:

Property	Type	Description	Example
user	string*	The UserID of the agent.	59abeb8c55f0992165e691fc
unreadCount	number	A counter of unseen messages.	0
active	boolean	Flag signifying if the conversation is currently active for the agent. Defaults to false.	false
inbox	boolean	Flag signifying if the conversation is currently in the agent’s inbox. Defaults to false.	false

conversation.touchpoints

A object containing the consumer touchpoints available to this conversation, keyed by the code name for this touchpoint; one of:

web
email
sms
facebook
whatsapp
video

Activated touchpoints will have one or more services specified.

Property	Type	Description	Example
services	array*	An array of Service IDs of services available for this touchpoint.	[58bcbafb8547f04f68c14bdb]
selected	boolean	Flag signifying if this is the currently active touchpoint. Defaults to true.	true

conversation.forms

Activated (unsent) forms that are amenable to completion and sending are available in the forms attribute.

Property	Type	Description	Example
form	string*	The Form ID of the form.	59abeb8c55f0992165e691fc
name	string*	Name of the form.	Brochure
type	enum	Form type. A `static` form always stays active, while a `topic` is picked by the agent. One of topic, static. Defaults to topic.	topic
category	string	Category name.	Used Car
categoryIndex	number	Index of the category in the organization’s category list.	0
values	MetaParams	Form key/values.	{MetaParams}

conversation.results

Processed forms are tracked in the results attribute.

Property	Type	Description	Example
message	string*	The Message ID of the results message.	5a23618654c8fe229c12f00c
form	string*	The Form ID of the form.	59abeb8c55f0992165e691fc
name	string*	Name of the form result.	Brochure
category	string	Category name.	Used Car
categoryIndex	number	Index of the category in the organization’s category list.	0

GET https://api.web1on1.chat/v2/conversations?sort=&offset=&limit=&select=&populate=&organization=&type=&status=&categoryIndex=&category=&slug=&participants.user=&forms.form=&results.form=&language=&meta.value=&createdAt=&updatedAt=

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "56467a06d9b082b0059151dc",
    "slug": "Byxu3buKiW",
    "url": "https://skynet.chat.report/c/Byxu3buKiW",
    "organization": "58bcbafb8547f04f68c14bdb",
    "name": "Bonbowack Acerfuse",
    "type": "bot",
    "status": "queued",
    "category": "Used Car",
    "categoryIndex": 0,
    "language": "en",
    "contact": "58bc9aecd906223dcec36493",
    "messages": [
      "58bcbafb8547f04f68c14bdb"
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "participants": [
      {
        "user": "59abeb8c55f0992165e691fc",
        "unreadCount": 0,
        "active": true,
        "inbox": true
      }
    ],
    "channels": [
      "56467a06d9b082b0059151dc"
    ],
    "channelsOffline": [
      "58bcbafb8547f04f68c14bdb"
    ],
    "touchpoints": {
      "web": {
        "services": [
          "58bcbafb8547f04f68c14bdb"
        ],
        "selected": true
      },
      "email": {
        "services": [
          "58bcbafb8547f04f68c14bdb"
        ],
        "selected": true
      },
      "sms": {
        "services": [
          "58bcbafb8547f04f68c14bdb"
        ],
        "selected": true
      },
      "facebook": {
        "services": [
          "58bcbafb8547f04f68c14bdb"
        ],
        "selected": true
      },
      "whatsapp": {
        "services": [
          "58bcbafb8547f04f68c14bdb"
        ],
        "selected": true
      },
      "video": {
        "services": [
          "58bcbafb8547f04f68c14bdb"
        ],
        "selected": true
      }
    },
    "forms": [
      {
        "form": "59abeb8c55f0992165e691fc",
        "name": "Brochure",
        "type": "topic",
        "category": "Used Car",
        "categoryIndex": 0,
        "values": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "results": [
      {
        "message": "5a23618654c8fe229c12f00c",
        "form": "59abeb8c55f0992165e691fc",
        "name": "Brochure",
        "category": "Used Car",
        "categoryIndex": 0
      }
    ],
    "createdBy": "58bc9aecd906223dcec36495",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Conversations
GET`/conversations{?sort,offset,limit,select,populate,organization,type,status,categoryIndex,category,slug,participants.user,forms.form,results.form,language,meta.value,createdAt,updatedAt}`

Return a list of conversations.

For fetching conversations using a query for a meta variable, at least one of the following parameters is required: id, type, participants.user, status, createdAt, categoryIndex, category, organization, createdAt or updatedAt.

URI Parameters

HideShow

sort: string (optional)
Sort order.
offset: number (optional)
Pagination start. Default: 0. Maximum 1000.
limit: number (optional)
Number of results. Default: 200. Maximum 1000.
select: string (optional)
Field selection.
populate: string (optional)
Field population.
organization: string (optional)
see object specification earlier.
type: string (optional)
see object specification earlier.
status: string (optional)
see object specification earlier.
categoryIndex: string (optional)
see object specification earlier.
category: string (optional)
see object specification earlier.
slug: string (optional)
see object specification earlier.
participants.user: string (optional)
see object specification earlier.
forms.form: string (optional)
see object specification earlier for additional forms properties.
results.form: string (optional)
see object specification earlier for additional results properties.
language: string (optional)
see object specification earlier.
meta.value: string (optional)
see object specification earlier.
createdAt: string (optional)
see object specification earlier.
updatedAt: string (optional)
see object specification earlier.

POST https://api.web1on1.chat/v2/conversations

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Bonbowack Acerfuse",
  "type": "bot",
  "status": "queued",
  "category": "Used Car",
  "categoryIndex": 0,
  "language": "en",
  "contact": "58bc9aecd906223dcec36493",
  "messages": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner."
    },
    "name": {
      "type": "string",
      "description": "Name for the conversation."
    },
    "type": {
      "type": "string",
      "enum": [
        "bot",
        "contact",
        "viewer",
        "agent",
        "admin",
        "system"
      ],
      "default": "bot",
      "description": "Conversation initiator type"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "closed"
      ],
      "default": "queued",
      "description": "Conversation status"
    },
    "category": {
      "type": "string",
      "description": "Category name."
    },
    "categoryIndex": {
      "type": "number",
      "description": "Index of the category in the organization's category list."
    },
    "language": {
      "type": "string",
      "description": "Conversation language."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the visitor."
    },
    "messages": {
      "type": "array",
      "description": "An array of Message IDs for this conversation."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
    }
  }
}

Responses202

Headers

Content-Type: application/json
Location: /conversations/56b9d54c59f2698e0ae9623c

Body

{
  "id": "56467a06d9b082b0059151dc",
  "slug": "Byxu3buKiW",
  "url": "https://skynet.chat.report/c/Byxu3buKiW",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Bonbowack Acerfuse",
  "type": "bot",
  "status": "queued",
  "category": "Used Car",
  "categoryIndex": 0,
  "language": "en",
  "contact": "58bc9aecd906223dcec36493",
  "messages": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "participants": [
    {
      "user": "59abeb8c55f0992165e691fc",
      "unreadCount": 0,
      "active": true,
      "inbox": true
    }
  ],
  "channels": [
    "56467a06d9b082b0059151dc"
  ],
  "channelsOffline": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "touchpoints": {
    "web": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "email": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "sms": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "facebook": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "whatsapp": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "video": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    }
  },
  "forms": [
    {
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "type": "topic",
      "category": "Used Car",
      "categoryIndex": 0,
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "message": "5a23618654c8fe229c12f00c",
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "category": "Used Car",
      "categoryIndex": 0
    }
  ],
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Conversation."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the conversation for use in short URL path segments."
    },
    "url": {
      "type": "string",
      "description": "Viewer URL."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner."
    },
    "name": {
      "type": "string",
      "description": "Name for the conversation."
    },
    "type": {
      "type": "string",
      "enum": [
        "bot",
        "contact",
        "viewer",
        "agent",
        "admin",
        "system"
      ],
      "default": "bot",
      "description": "Conversation initiator type"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "closed"
      ],
      "default": "queued",
      "description": "Conversation status"
    },
    "category": {
      "type": "string",
      "description": "Category name."
    },
    "categoryIndex": {
      "type": "number",
      "description": "Index of the category in the organization's category list."
    },
    "language": {
      "type": "string",
      "description": "Conversation language."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the visitor."
    },
    "messages": {
      "type": "array",
      "description": "An array of Message IDs for this conversation."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
    },
    "participants": {
      "type": "array",
      "description": "An array of conversation participants."
    },
    "channels": {
      "type": "array",
      "description": "An array of Channel IDs that were notified for this conversation."
    },
    "channelsOffline": {
      "type": "array",
      "description": "An array of Channel IDs that were not notified due to unavailability of agents."
    },
    "touchpoints": {
      "type": "object",
      "properties": {
        "web": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Live Chat channel."
        },
        "email": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Email channel."
        },
        "sms": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the SMS channel."
        },
        "facebook": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Facebook Messenger channel."
        },
        "whatsapp": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the WhatsApp channel."
        },
        "video": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Jitsi videochat channel."
        }
      },
      "description": "Touchpoints object representing consumer channels."
    },
    "forms": {
      "type": "array",
      "description": "An array of incomplete or unsent forms."
    },
    "results": {
      "type": "array",
      "description": "An array of completed and sent forms."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the conversation."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was last modified."
    }
  }
}

Create a new Conversation
POST`/conversations`

Create a conversation using this action.

Conversation ¶

GET https://api.web1on1.chat/v2/conversations/conversation_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56467a06d9b082b0059151dc",
  "slug": "Byxu3buKiW",
  "url": "https://skynet.chat.report/c/Byxu3buKiW",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Bonbowack Acerfuse",
  "type": "bot",
  "status": "queued",
  "category": "Used Car",
  "categoryIndex": 0,
  "language": "en",
  "contact": "58bc9aecd906223dcec36493",
  "messages": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "participants": [
    {
      "user": "59abeb8c55f0992165e691fc",
      "unreadCount": 0,
      "active": true,
      "inbox": true
    }
  ],
  "channels": [
    "56467a06d9b082b0059151dc"
  ],
  "channelsOffline": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "touchpoints": {
    "web": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "email": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "sms": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "facebook": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "whatsapp": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "video": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    }
  },
  "forms": [
    {
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "type": "topic",
      "category": "Used Car",
      "categoryIndex": 0,
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "message": "5a23618654c8fe229c12f00c",
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "category": "Used Car",
      "categoryIndex": 0
    }
  ],
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Conversation."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the conversation for use in short URL path segments."
    },
    "url": {
      "type": "string",
      "description": "Viewer URL."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner."
    },
    "name": {
      "type": "string",
      "description": "Name for the conversation."
    },
    "type": {
      "type": "string",
      "enum": [
        "bot",
        "contact",
        "viewer",
        "agent",
        "admin",
        "system"
      ],
      "default": "bot",
      "description": "Conversation initiator type"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "closed"
      ],
      "default": "queued",
      "description": "Conversation status"
    },
    "category": {
      "type": "string",
      "description": "Category name."
    },
    "categoryIndex": {
      "type": "number",
      "description": "Index of the category in the organization's category list."
    },
    "language": {
      "type": "string",
      "description": "Conversation language."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the visitor."
    },
    "messages": {
      "type": "array",
      "description": "An array of Message IDs for this conversation."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
    },
    "participants": {
      "type": "array",
      "description": "An array of conversation participants."
    },
    "channels": {
      "type": "array",
      "description": "An array of Channel IDs that were notified for this conversation."
    },
    "channelsOffline": {
      "type": "array",
      "description": "An array of Channel IDs that were not notified due to unavailability of agents."
    },
    "touchpoints": {
      "type": "object",
      "properties": {
        "web": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Live Chat channel."
        },
        "email": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Email channel."
        },
        "sms": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the SMS channel."
        },
        "facebook": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Facebook Messenger channel."
        },
        "whatsapp": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the WhatsApp channel."
        },
        "video": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Jitsi videochat channel."
        }
      },
      "description": "Touchpoints object representing consumer channels."
    },
    "forms": {
      "type": "array",
      "description": "An array of incomplete or unsent forms."
    },
    "results": {
      "type": "array",
      "description": "An array of completed and sent forms."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the conversation."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was last modified."
    }
  }
}

Retrieve a Conversation
GET`/conversations/{conversation_id}`

Returns a specific Conversation.

URI Parameters

HideShow

conversation_id: string (required)
ID of the Conversation.

PATCH https://api.web1on1.chat/v2/conversations/conversation_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Bonbowack Acerfuse",
  "type": "bot",
  "status": "queued",
  "category": "Used Car",
  "categoryIndex": 0,
  "language": "en",
  "contact": "58bc9aecd906223dcec36493",
  "messages": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner."
    },
    "name": {
      "type": "string",
      "description": "Name for the conversation."
    },
    "type": {
      "type": "string",
      "enum": [
        "bot",
        "contact",
        "viewer",
        "agent",
        "admin",
        "system"
      ],
      "default": "bot",
      "description": "Conversation initiator type"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "closed"
      ],
      "default": "queued",
      "description": "Conversation status"
    },
    "category": {
      "type": "string",
      "description": "Category name."
    },
    "categoryIndex": {
      "type": "number",
      "description": "Index of the category in the organization's category list."
    },
    "language": {
      "type": "string",
      "description": "Conversation language."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the visitor."
    },
    "messages": {
      "type": "array",
      "description": "An array of Message IDs for this conversation."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56467a06d9b082b0059151dc",
  "slug": "Byxu3buKiW",
  "url": "https://skynet.chat.report/c/Byxu3buKiW",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Bonbowack Acerfuse",
  "type": "bot",
  "status": "queued",
  "category": "Used Car",
  "categoryIndex": 0,
  "language": "en",
  "contact": "58bc9aecd906223dcec36493",
  "messages": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "participants": [
    {
      "user": "59abeb8c55f0992165e691fc",
      "unreadCount": 0,
      "active": true,
      "inbox": true
    }
  ],
  "channels": [
    "56467a06d9b082b0059151dc"
  ],
  "channelsOffline": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "touchpoints": {
    "web": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "email": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "sms": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "facebook": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "whatsapp": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    },
    "video": {
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    }
  },
  "forms": [
    {
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "type": "topic",
      "category": "Used Car",
      "categoryIndex": 0,
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "message": "5a23618654c8fe229c12f00c",
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "category": "Used Car",
      "categoryIndex": 0
    }
  ],
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Conversation."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the conversation for use in short URL path segments."
    },
    "url": {
      "type": "string",
      "description": "Viewer URL."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner."
    },
    "name": {
      "type": "string",
      "description": "Name for the conversation."
    },
    "type": {
      "type": "string",
      "enum": [
        "bot",
        "contact",
        "viewer",
        "agent",
        "admin",
        "system"
      ],
      "default": "bot",
      "description": "Conversation initiator type"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "closed"
      ],
      "default": "queued",
      "description": "Conversation status"
    },
    "category": {
      "type": "string",
      "description": "Category name."
    },
    "categoryIndex": {
      "type": "number",
      "description": "Index of the category in the organization's category list."
    },
    "language": {
      "type": "string",
      "description": "Conversation language."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the visitor."
    },
    "messages": {
      "type": "array",
      "description": "An array of Message IDs for this conversation."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
    },
    "participants": {
      "type": "array",
      "description": "An array of conversation participants."
    },
    "channels": {
      "type": "array",
      "description": "An array of Channel IDs that were notified for this conversation."
    },
    "channelsOffline": {
      "type": "array",
      "description": "An array of Channel IDs that were not notified due to unavailability of agents."
    },
    "touchpoints": {
      "type": "object",
      "properties": {
        "web": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Live Chat channel."
        },
        "email": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Email channel."
        },
        "sms": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the SMS channel."
        },
        "facebook": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Facebook Messenger channel."
        },
        "whatsapp": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the WhatsApp channel."
        },
        "video": {
          "type": "object",
          "properties": {
            "services": {
              "type": "array",
              "description": "An array of Service IDs of services available for this touchpoint."
            },
            "selected": {
              "type": "boolean",
              "description": "Flag signifying if this is the currently active touchpoint.",
              "default": true
            }
          },
          "required": [
            "services"
          ],
          "description": "Touchpoint representing the Jitsi videochat channel."
        }
      },
      "description": "Touchpoints object representing consumer channels."
    },
    "forms": {
      "type": "array",
      "description": "An array of incomplete or unsent forms."
    },
    "results": {
      "type": "array",
      "description": "An array of completed and sent forms."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the conversation."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was last modified."
    }
  }
}

Update a Conversation
PATCH`/conversations/{conversation_id}`

Update a specific Conversation. To be used only under special circumstances (eg corruption repairs); during regular operations, conversation state should be updated by creating messages containing the /set command.

URI Parameters

HideShow

conversation_id: string (required)
ID of the Conversation.

DELETE https://api.web1on1.chat/v2/conversations/conversation_id

Responses204

This response has no content.

Delete a Conversation
DELETE`/conversations/{conversation_id}`

Delete a Conversation. The full associated contact record (if any), and all conversation messages are deleted.

This method is useful for deleting test conversations, or to comply with GDPR requests for data removal.

URI Parameters

HideShow

conversation_id: string (required)
ID of the Conversation.

Conversation Search ¶

GET https://api.web1on1.chat/v2/conversations/search?q

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Search for Conversations
GET`/conversations/search?q`

Returns conversations that their results, forms, names or entities matches the search query terms

URI Parameters

HideShow

q: string (required)
Search term

Conversation Links ¶

GET https://api.web1on1.chat/v2/links/?conversation=

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "web": "https://api.web1on1.chat/web/631ef94dc1f44e00f4de68f3",
  "whatsapp": "https://wa.me/15144441919?text=2224145698%20is%20my%20code,%20I%20want%20to%20continue%20my%20conversation%20on%20WhatsApp.",
  "messenger": "https://m.me/123456781234567?ref=lr_K4DBnWEiWv6LR-CP0j_5FFcl"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "web": {
      "type": "string",
      "description": "Web channel transfer link."
    },
    "whatsapp": {
      "type": "string",
      "description": "WhatsApp channel transfer link."
    },
    "messenger": {
      "type": "string",
      "description": "Facebook Messenger channel transfer link."
    }
  },
  "required": [
    "web"
  ]
}

List Links
GET`/links/{?conversation}`

Returns links of conversations, with these links you’re able to switch between touchpoints. For example switching between Web and WhatsApp.

URI Parameters

HideShow

conversation: string (required)
ID of the Conversation.

GET https://api.web1on1.chat/v2/conversations/conversation_id/links

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "web": "https://api.web1on1.chat/web/631ef94dc1f44e00f4de68f3",
  "whatsapp": "https://wa.me/15144441919?text=2224145698%20is%20my%20code,%20I%20want%20to%20continue%20my%20conversation%20on%20WhatsApp.",
  "messenger": "https://m.me/123456781234567?ref=lr_K4DBnWEiWv6LR-CP0j_5FFcl"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "web": {
      "type": "string",
      "description": "Web channel transfer link."
    },
    "whatsapp": {
      "type": "string",
      "description": "WhatsApp channel transfer link."
    },
    "messenger": {
      "type": "string",
      "description": "Facebook Messenger channel transfer link."
    }
  },
  "required": [
    "web"
  ]
}

List Conversation Links
GET`/conversations/{conversation_id}/links`

Returns links of conversations, with these links you’re able to switch between touchpoints. For example switching betwee Web and WhatsApp.

URI Parameters

HideShow

conversation_id: string (required)
ID of the Conversation.

Messages ¶

A Message represents an event in the Conversation timeline. Commonly this is a text message from a participant, but a Message may also represent commands and fields for example. It has the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the Message.	56467a06d9b082b0059151dc
organization	string	Organization ID, conversation owner. Same as the organization owning the conversation.	58bcbafb8547f04f68c14bdb
contact	string	Contact ID of the consumer that created or received the message, if applicable. Same as the conversation contact.	58bc9aecd906223dcec36493
slug	string	Slug for the message for use in viewer URL path segments.	SJXlgkVbaZ
url	string	The (possibly white labeled) URL of the message in the viewer.	https://view.web1on1.chat/m/SJXlgkVbaZ
conversation	string*	Conversation ID.	58bc9aecd906223dcec36493
text	string*	Message text or HTML, or the URL of a non-text contentType.	Hello 😉
type	enum	Message type One of chat, card, postback, mention, tag, search, command, form, field, results, report, status. Defaults to chat.	chat
role	enum	Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages. One of contact, agent, bot, system. Defaults to bot.	contact
isBackchannel	boolean	Wether the message is part of the `back channel` stream aside the main conversation thread. Defaults to true.	true
contentType	enum	Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages. One of text/plain, text/html, text/url, image/png, image/gif, image/jpg, image/jpeg, application/pdf. Defaults to text/plain.	text/plain
user	string	User ID of the agent that is represented by the message, if applicable (default: user making the API request).	58bc9aecd906223dcec36495
service	string	Service ID of external service that this message gets mirrored with (either as a sender or as a receiver).	58bc9aecd906223dcec36493
touchpoint	enum	Touchpoint/platform source or target at service for this message. One of web, email, sms, facebook, whatsapp. Defaults to web.	web
delay	number	Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown.	5000
items	array	An array of list items to present to participants, each item containing one or more actions.	[{ListItem}]
actions	array	An array of Action Buttons to present to participants, to serve as a link, reply or postback actions.	[{ActionButton}]
results	array	An array of form results objects that were collected from messages with type `results`.	[{MessageResults}]
meta	MetaParams	Free-form object of key-value pairs, representing context from the service adapter that created this message.	{MetaParams}
serviceType	enum	Target type of service provider. One of smartsupp, intercom, smooch, twilio, mailgun, messenger, whatsapp, api, webhook. Defaults to smartsupp.	smartsupp
createdBy	string	User ID of the user that created the message.	58bc9aecd906223dcec36495
createdAt	string	ISO8601 date and time when the Message was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time when the Message was last modified.	2016-01-07T14:03:43Z

Message Items

Message Items can be sent by including them in the message payload. Only messages of type chat, card or postback support message items.

Property	Type	Description	Example
title	string*	The title of the item.	Tacos
description	string	The text description, or subtitle.	Beef and cheese, hmmm…
actions	array	Array of message actions. At least 1 is required, a maximum of 3 are allowed. link, webview, and postback actions are supported. See the action schema for details.	[{ActionButton}]
size	enum	The size of the image to be shown in the carousel/list item (Only top item of Facebook Messenger carousel) One of compact, large. Defaults to compact.	compact
mediaUrl	string	The image URL to be shown in the carousel/list item.	http://example.org/image.png
mediaType	string	If a mediaUrl was specified, the media type is defined here, for example ‘image/jpeg’. If mediaType is not specified, the media type will be resolved with the mediaUrl.	image/png

Action Buttons

Actions buttons can be sent by including them in the message payload. There are 5 types of supported actions : link, reply, postback, webview and locationRequest. Type must be specified by providing a type argument in the action object.

Link

A link action will open the provided URI when tapped. Links outside the Web1on1 domain will open in a new browser tab.

Property	Type	Description	Example
type	string*	Button type `link`.	link
text	string*	The button text.	Tacos
uri	string	The action URI. This is the link that will be used in the clients when clicking the button.	http://example.org
meta	MetaParams	Flat object containing any custom properties associated with the action.	{MetaParams}

Postback

A postback action will post the action payload to the server.

Property	Type	Description	Example
type	string*	Button type `postback`.	postback
text	string*	The button text.	Tacos
payload	string*	A string payload to help you identify the action context. If the payload represents a JSON message object or array of message objects, these will be processed as conversation messages when the button is clicked. You can also use metadata for more complex needs.	tacos
meta	MetaParams	Flat object containing any custom properties associated with the action.	{MetaParams}

Reply

A reply action will echo the user’s choice as a message. You may optionally specify an iconUrl which will render as an icon for each option.

Property	Type	Description	Example
type	string*	Button type `reply`.	reply
text	string*	The button text.	Tacos
payload	string*	A string payload to help you identify the action context. Used when posting the reply. If the payload represents a JSON message object or array of message objects, these will be processed as conversation messages when the button is clicked. You can also use metadata for more complex needs.	tacos
iconUrl	string	An icon to render next to the reply option (Facebook Messenger and Web Messenger only).	http://example.com/images/tag.png
meta	MetaParams	Flat object containing any custom properties associated with the action.	{MetaParams}

reply type actions can be sent either alone or with location request actions. If an action of a different type is included in the message, it will be rejected.
Icons are currently only supported on Facebook Messenger and Web Messenger.

Webview

When a webview actions is clicked/tapped, the provided URI will be loaded in a webview. Channels that do not support webviews will open the fallback URI instead.

Property	Type	Description	Example
type	string*	Button type `webview`.	webview
text	string*	The button text.	Open Form
uri	string*	The webview URI. This is the URI that will open in the webview when clicking the button.	http://example.org
fallback	string*	The webview fallback URI. This is the link that will be opened in channels that do not support webviews.	http://example.org
size	enum	Controls the webview height. One of compact, tall, full. Defaults to compact.	compact
meta	MetaParams	Flat object containing any custom properties associated with the action.	{MetaParams}

Location Request

A location request action will prompt the user to share their location. Unsupported clients will receive text fallback: “App has requested a location”.

Property	Type	Description	Example
type	string*	Button type `locationRequest`.	locationRequest
text	string*	The button text.	Set Location
meta	MetaParams	Flat object containing any custom properties associated with the action.	{MetaParams}

locationRequest type actions can be sent either alone or with reply actions. If an action of a different type is included in the message, it will be rejected.

GET https://api.web1on1.chat/v2/messages?sort=&offset=&limit=&select=&populate=&conversation=&organization=&type=&role=&isBackchannel=&contentType=&touchpoint=&delay=&user=&text=&meta=&createdBy=

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "56467a06d9b082b0059151dc",
    "organization": "58bcbafb8547f04f68c14bdb",
    "contact": "58bc9aecd906223dcec36493",
    "slug": "SJXlgkVbaZ",
    "url": "https://view.web1on1.chat/m/SJXlgkVbaZ",
    "conversation": "58bc9aecd906223dcec36493",
    "text": "Hello ;-)",
    "type": "chat",
    "role": "contact",
    "isBackchannel": false,
    "contentType": "text/plain",
    "user": "58bc9aecd906223dcec36495",
    "service": "58bc9aecd906223dcec36493",
    "touchpoint": "web",
    "delay": 5000,
    "items": [
      {
        "title": "Tacos",
        "description": "Beef and cheese, hmmm...",
        "actions": [
          {
            "type": "link",
            "text": "Tacos",
            "iconUrl": "http://example.com/images/tag.png",
            "payload": "tacos",
            "uri": "http://example.org",
            "meta": {
              "someKey": "Some value",
              "anotherKey": "Some other value"
            }
          }
        ],
        "size": "compact",
        "mediaUrl": "http://example.org/image.png",
        "mediaType": "image/png"
      }
    ],
    "actions": [
      {
        "type": "link",
        "text": "Tacos",
        "iconUrl": "http://example.com/images/tag.png",
        "payload": "tacos",
        "uri": "http://example.org",
        "meta": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "results": [
      {
        "form": "590d3af9e025187959e5e11c",
        "formName": "Identifiers",
        "type": "static",
        "values": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "serviceType": "smartsupp",
    "createdBy": "58bc9aecd906223dcec36495",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Messages
GET`/messages{?sort,offset,limit,select,populate,conversation,organization,type,role,isBackchannel,contentType,touchpoint,delay,user,text,meta,createdBy}`

Return a list of all Messages. At least one of the following parameters should be supplied: id, organization, conversation, type, role or createdAt.

URI Parameters

HideShow

sort: string (optional)
Sort order.
offset: number (optional)
Pagination start. Default: 0. Maximum 1000.
limit: number (optional)
Number of results. Default: 200. Maximum 1000.
select: string (optional)
Field selection.
populate: string (optional)
Field population.
conversation: string (optional)
ID of the Conversation.
organization: string (optional)
ID of the Organization.
type: string (optional)
Message type.
role: string (optional)
Message role.
isBackchannel: boolean (optional)
Backchannel flag.
contentType: string (optional)
MIME type of the message content.
touchpoint: string (optional)
Consumer endpoint type.
delay: integer (optional)
Number of milliseconds to postpone message processing.
user: string (optional)
ID of the user.
text: string (optional)
Message text.
meta: string (optional)
Meta variable.
createdBy: string (optional)
ID of the creating user.

GET https://api.web1on1.chat/v2/conversation/conversation_id/messages?sort=&offset=&limit=&select=&populate=&type=&type=&role=&isBackchannel=&contentType=&touchpoint=&delay=&user=&text=&meta=&createdBy=

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "56467a06d9b082b0059151dc",
    "organization": "58bcbafb8547f04f68c14bdb",
    "contact": "58bc9aecd906223dcec36493",
    "slug": "SJXlgkVbaZ",
    "url": "https://view.web1on1.chat/m/SJXlgkVbaZ",
    "conversation": "58bc9aecd906223dcec36493",
    "text": "Hello ;-)",
    "type": "chat",
    "role": "contact",
    "isBackchannel": false,
    "contentType": "text/plain",
    "user": "58bc9aecd906223dcec36495",
    "service": "58bc9aecd906223dcec36493",
    "touchpoint": "web",
    "delay": 5000,
    "items": [
      {
        "title": "Tacos",
        "description": "Beef and cheese, hmmm...",
        "actions": [
          {
            "type": "link",
            "text": "Tacos",
            "iconUrl": "http://example.com/images/tag.png",
            "payload": "tacos",
            "uri": "http://example.org",
            "meta": {
              "someKey": "Some value",
              "anotherKey": "Some other value"
            }
          }
        ],
        "size": "compact",
        "mediaUrl": "http://example.org/image.png",
        "mediaType": "image/png"
      }
    ],
    "actions": [
      {
        "type": "link",
        "text": "Tacos",
        "iconUrl": "http://example.com/images/tag.png",
        "payload": "tacos",
        "uri": "http://example.org",
        "meta": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "results": [
      {
        "form": "590d3af9e025187959e5e11c",
        "formName": "Identifiers",
        "type": "static",
        "values": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "serviceType": "smartsupp",
    "createdBy": "58bc9aecd906223dcec36495",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Conversation Messages
GET`/conversation/{conversation_id}/messages{?sort,offset,limit,select,populate,type,type,role,isBackchannel,contentType,touchpoint,delay,user,text,meta,createdBy}`

Return a list of all Messages in a Conversation.

URI Parameters

HideShow

sort: string (optional)
Sort order.
offset: number (optional)
Pagination start. Default: 0. Maximum 1000.
limit: number (optional)
Number of results. Default: 200. Maximum 1000.
select: string (optional)
Field selection.
populate: string (optional)
Field population.
conversation_id: string (optional)
ID of the Conversation.
type: string (optional)
Message type.
role: string (optional)
Message role.
isBackchannel: boolean (optional)
Backchannel flag.
contentType: string (optional)
MIME type of the message content.
touchpoint: string (optional)
Consumer endpoint type.
delay: integer (optional)
Number of milliseconds to postpone message processing.
user: string (optional)
ID of the user.
text: string (optional)
Message text.
meta: string (optional)
Meta variable.
createdBy: string (optional)
ID of the creating user.

POST https://api.web1on1.chat/v2/messages

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
    }
  },
  "required": [
    "conversation",
    "text"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /messages/56467a06d9b082b0059151dc

Body

{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "contact": "58bc9aecd906223dcec36493",
  "slug": "SJXlgkVbaZ",
  "url": "https://view.web1on1.chat/m/SJXlgkVbaZ",
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "serviceType": "smartsupp",
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Message."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Same as the organization owning the conversation."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the consumer that created or received the message, if applicable. Same as the conversation contact."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the message for use in viewer URL path segments."
    },
    "url": {
      "type": "string",
      "description": "The (possibly white labeled) URL of the message in the viewer."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
    },
    "serviceType": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "whatsapp",
        "api",
        "webhook"
      ],
      "default": "smartsupp",
      "description": "Target type of service provider."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the message."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was last modified."
    }
  },
  "required": [
    "conversation",
    "text"
  ]
}

Create a new Message
POST`/messages`

You may create a new message using this action.

POST https://api.web1on1.chat/v2/conversation/conversation_id/messages

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
    }
  },
  "required": [
    "conversation",
    "text"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /messages/56467a06d9b082b0059151dc

Body

{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "contact": "58bc9aecd906223dcec36493",
  "slug": "SJXlgkVbaZ",
  "url": "https://view.web1on1.chat/m/SJXlgkVbaZ",
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "serviceType": "smartsupp",
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Message."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Same as the organization owning the conversation."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the consumer that created or received the message, if applicable. Same as the conversation contact."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the message for use in viewer URL path segments."
    },
    "url": {
      "type": "string",
      "description": "The (possibly white labeled) URL of the message in the viewer."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
    },
    "serviceType": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "whatsapp",
        "api",
        "webhook"
      ],
      "default": "smartsupp",
      "description": "Target type of service provider."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the message."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was last modified."
    }
  },
  "required": [
    "conversation",
    "text"
  ]
}

Create a new Conversation Message
POST`/conversation/{conversation_id}/messages`

You may create a new message using this action.

URI Parameters

HideShow

conversation_id: string (required)
ID of the Conversation.

Message ¶

GET https://api.web1on1.chat/v2/messages/message_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "contact": "58bc9aecd906223dcec36493",
  "slug": "SJXlgkVbaZ",
  "url": "https://view.web1on1.chat/m/SJXlgkVbaZ",
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "serviceType": "smartsupp",
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Message."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Same as the organization owning the conversation."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the consumer that created or received the message, if applicable. Same as the conversation contact."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the message for use in viewer URL path segments."
    },
    "url": {
      "type": "string",
      "description": "The (possibly white labeled) URL of the message in the viewer."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
    },
    "serviceType": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "whatsapp",
        "api",
        "webhook"
      ],
      "default": "smartsupp",
      "description": "Target type of service provider."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the message."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was last modified."
    }
  },
  "required": [
    "conversation",
    "text"
  ]
}

Retrieve a Message
GET`/messages/{message_id}`

Returns a specific Message.

URI Parameters

HideShow

message_id: string (required)
ID of the Message.

PATCH https://api.web1on1.chat/v2/messages/message_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
    }
  },
  "required": [
    "conversation",
    "text"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "contact": "58bc9aecd906223dcec36493",
  "slug": "SJXlgkVbaZ",
  "url": "https://view.web1on1.chat/m/SJXlgkVbaZ",
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "serviceType": "smartsupp",
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Message."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Same as the organization owning the conversation."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the consumer that created or received the message, if applicable. Same as the conversation contact."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the message for use in viewer URL path segments."
    },
    "url": {
      "type": "string",
      "description": "The (possibly white labeled) URL of the message in the viewer."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
    },
    "serviceType": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "whatsapp",
        "api",
        "webhook"
      ],
      "default": "smartsupp",
      "description": "Target type of service provider."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the message."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was last modified."
    }
  },
  "required": [
    "conversation",
    "text"
  ]
}

Update a Message
PATCH`/messages/{message_id}`

Update a specific message.

URI Parameters

HideShow

message_id: string (required)
ID of the Message.

DELETE https://api.web1on1.chat/v2/messages/message_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete a Message
DELETE`/messages/{message_id}`

Delete a specific message.

URI Parameters

HideShow

message_id: string (required)
ID of the Message.

Attachments ¶

An Attachment represents a file shared by agents, that can be added as a message on conversations. The supported extentions for attachments are .pdf, .jpg, .jpeg, .gif and .png. It has the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the Attachment.	5c803bd73b4d575d98bbdd66
originalName	string	Original filename.	sample.pdf or sample.jpg
filename	string	Storage filename.	1551907796182-Sample image.jpg
url	string	Link to the file.	https://storage.googleapis.com/cs2-uploads/attachments/58bcbafb8547f04f68c14bdb/58bc9aecd906223dcec36495/58bc9aecd906223dcec36493/1551907796182-Sample image.jpg
mimetype	string	File mime-type. One of image/png, image/gif, image/jpeg, application/pdf.	image/jpeg
bytes	number	Uploaded file size.	425528
path	string	Server file path.	attachments/58bcbafb8547f04f68c14bdb/58bc9aecd906223dcec36495/5c803b5a9a390d56b8357a0d/1551907796182-Sample%20image.jpg
createdBy	string	User ID of the user that created the attachment.	58bc9aecd906223dcec36495
organization	string	Organization ID, conversation owner. Same as the organization owning the conversation.	58bcbafb8547f04f68c14bdb
conversation	string	Conversation ID.	58bc9aecd906223dcec36493
createdAt	string	ISO8601 date and time when the Message was created.	2019-03-06T21:29:59.912Z
updatedAt	string	ISO8601 date and time when the Message was last modified.	2019-03-06T21:29:59.912Z

GET https://api.web1on1.chat/v2/conversations/conversation_id/attachments

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5c803bd73b4d575d98bbdd66",
  "originalName": "sample.jpg",
  "filename": "'1551907796182",
  "url": "https://storage.googleapis.com/cs2-uploads/attachments/58bcbafb8547f04f68c14bdb/58bc9aecd906223dcec36495/58bc9aecd906223dcec36493/1551907796182-Sample%20image.jpg",
  "mimetype": "image/png",
  "bytes": 425528,
  "path": "attachments/58bcbafb8547f04f68c14bdb/58bc9aecd906223dcec36495/5c803b5a9a390d56b8357a0d/1551907796182-Sample%20image.jpg",
  "createdBy": "58bc9aecd906223dcec36495",
  "organization": "58bcbafb8547f04f68c14bdb",
  "conversation": "58bc9aecd906223dcec36493",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Attachment."
    },
    "originalName": {
      "type": "string",
      "description": "Original filename."
    },
    "filename": {
      "type": "string",
      "description": "Sample image.jpg' (string) - Storage filename."
    },
    "url": {
      "type": "string",
      "description": "Link to the file."
    },
    "mimetype": {
      "type": "string",
      "enum": [
        "image/png",
        "image/gif",
        "image/jpeg",
        "application/pdf"
      ],
      "description": "File mime-type."
    },
    "bytes": {
      "type": "number",
      "description": "Uploaded file size."
    },
    "path": {
      "type": "string",
      "description": "Server file path."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the message."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Same as the organization owning the conversation."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was last modified."
    }
  },
  "required": [
    "conversation"
  ]
}

Retrieve Attachments
GET`/conversations/{conversation_id}/attachments`

Return all attachments related for a given conversation.

URI Parameters

HideShow

conversation_id: string (required)
ID of the conversation.

POST https://api.web1on1.chat/v2/conversations/conversation_id/attachments

Requestsexample 1

Headers

Content-Type: multipart/form-data;boundary=---BOUNDARY
Authorization: Bearer <token>

Body

---BOUNDARY
Content-Disposition: form-data; name="title"
Content-Type: text/plain

Sample file
---BOUNDARY--
Content-Disposition: form-data; name="file"; filename="sample.pdf"
Content-Type: application/pdf
Content-Transfer-Encoding: base64

/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIA
AhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEB
AAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AD//Z
-----BOUNDARY

Responses201

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "id": "5c803bd73b4d575d98bbdd66",
  "originalName": "sample.jpg",
  "filename": "'1551907796182",
  "url": "https://storage.googleapis.com/cs2-uploads/attachments/58bcbafb8547f04f68c14bdb/58bc9aecd906223dcec36495/58bc9aecd906223dcec36493/1551907796182-Sample%20image.jpg",
  "bytes": 425528,
  "mimetype": "image/png"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Attachment."
    },
    "originalName": {
      "type": "string",
      "description": "Original filename."
    },
    "filename": {
      "type": "string",
      "description": "Sample image.jpg' (string) - Storage filename."
    },
    "url": {
      "type": "string",
      "description": "Link to the file."
    },
    "bytes": {
      "type": "number",
      "description": "Uploaded file size."
    },
    "mimetype": {
      "type": "string",
      "enum": [
        "image/png",
        "image/gif",
        "image/jpeg",
        "application/pdf"
      ],
      "description": "File mime-type."
    }
  }
}

Upload Attachment
POST`/conversations/{conversation_id}/attachments`

Use this action to upload an attachment, for the given conversation, into the CDN.

URI Parameters

HideShow

conversation_id: string (required)
ID of the conversation.

DELETE https://api.web1on1.chat/v2/conversations/conversation_id/attachments/attachment_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete Attachments
DELETE`/conversations/{conversation_id}/attachments/{attachment_id}`

Delete an attachment on a given conversation.

URI Parameters

HideShow

conversation_id: string (required)
ID of the conversation.
attachment_id: string (required)
ID of the attachment

Contacts ¶

Contacts represent visitors to your web properties. Each time a new conversation is started by one of your website visitors, a new Contact resource - if it doesn’t exist yet - will be created for the visitor.

A Contact record has the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the Contact.	56467a06d9b082b0059151dc
organization	string	The ID of the organization that owns the Contact.	5a12329862eca153b1db4354
conversation	string	The ID of the conversation assigned to this Contact.	5a1d8cd2cff15226e10e00b7
blockUntil	string	ISO8601 date and time to release any contact block (suppressing of messages).	2016-01-07T14:03:43Z
presences	array	An array of known service presences for the Contact.	[{ContactPresence}]
profile	ContactProfile	Contact profile data.	{ContactProfile}
links	array	An array of known external profile/service URLs for the Contact.	[{ContactLink}]
createdAt	string	ISO8601 date and time of when the Contact was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of when the Contact was last modified.	2016-01-07T14:03:43Z

Each contact record keeps track of presences at various endpoint services:

Property	Type	Description	Example
service	string*	The ID of the Service.	56467a06d9b082b0059151dc
remoteDeviceId	string*	Contact cookie/device identifier at the Service.	ANgGx5u*RxqH
remoteContactId	string*	Contact identifier at the Service.	8dPLapu2017@s1.smartsupp.com
remoteRoomId	string*	Contact identifier at the Service.	uid3710@s1.smartsupp.com/95f217
platform	enum	Touchpoint/platform source or target at service for this message. One of web, email, sms, messenger, whatsapp. Defaults to web.	web
status	enum	Presence status. One of unknown, offline, online, busy, waiting, idle, away, available. Defaults to unknown.	unknown
meta	MetaParams	Free-form object of key-values.	{MetaParams}

Contact profile information is available as the profile object, with optional attributes:

Property	Type	Description	Example
name	string	Full name of the Contact, in cases where givenName and familyName entry methods are not available.	John Doe
initials	string	Contact initials	J.
givenName	string	Contact given name or first name	John
familyName	string	Contact family name or surname	Doe
additionalName	string	Contact middle name, if applicable	William
honorificPrefix	string	Name prefix	Dr.
honorificSuffix	string	Name suffix	esq.
gender	enum	Contact biological sex One of unknown, male, female, indeterminate. Defaults to unknown.	unknown
address	Address	Address object	{Address}
telephone	string	Contact telephone number	+31209876543
email	string	Contact email address	john@example.com
worksFor	string	Primary organization that the contact works for	Acme, Inc.

In addition, links to external services can be stored in the links object:

Property	Type	Description	Example
label	string*	The name of the external service.	Instagram
url	string*	URL of the contact profile at the external service.	https://instagr.am/49764674
icon	string	Contact identifier at the Service.	https://cdn.web1on1.chat/icons/instagram.png

The profile’s Address object has the following attributes, all optional:

Property	Type	Description	Example
streetAddress	string	Address street name	Downing street
streetNumber	string	Address street number	10
addressLocality	string	City or town	London
addressRegion	string	Region	London
postalCode	string	Address location zip/postal code	SW1A 2AA
addressCountry	string	ISO 3166-1 alpha-2 2-letter country code of address location.	UK

Contact name field conventions are adapted from JSON-LD standards as specified by Google and described at Schema.org:

Address field name conventions are also as specified at Schema.org:

https://schema.org/PostalAddress

GET https://api.web1on1.chat/v2/messages?sort=&offset=&limit=&select=&populate=&q=&conversation=&organization=&profile.name=&data.MyCarVIN=&meta=&createdBy=

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "56467a06d9b082b0059151dc",
    "organization": "5a12329862eca153b1db4354",
    "conversation": "5a1d8cd2cff15226e10e00b7",
    "blockUntil": "2016-01-07T14:03:43Z",
    "presences": [
      {
        "service": "56467a06d9b082b0059151dc",
        "remoteDeviceId": "ANgGx5u*RxqH",
        "remoteContactId": "8dPLapu2017@s1.smartsupp.com",
        "remoteRoomId": "uid3710@s1.smartsupp.com/95f217",
        "platform": "web",
        "status": "unknown",
        "meta": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "profile": {
      "name": "John Doe",
      "initials": "J.",
      "givenName": "John",
      "familyName": "Doe",
      "additionalName": "William",
      "honorificPrefix": "Dr.",
      "honorificSuffix": "esq.",
      "gender": "unknown",
      "address": {
        "streetAddress": "Downing street",
        "streetNumber": "10",
        "addressLocality": "London",
        "addressRegion": "London",
        "postalCode": "SW1A 2AA",
        "addressCountry": "UK"
      },
      "telephone": "+31209876543",
      "email": "john@example.com",
      "worksFor": "Acme, Inc."
    },
    "links": [
      {
        "label": "Instagram",
        "url": "https://instagr.am/49764674",
        "icon": "https://cdn.web1on1.chat/icons/instagram.png"
      }
    ],
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List Contacts
GET`/messages{?sort,offset,limit,select,populate,q,conversation,organization,profile.name,data.MyCarVIN,meta,createdBy}`

Return a list of contacts matching the criteria provided.

URI Parameters

HideShow

sort: string (optional)
Sort order.
offset: number (optional)
Pagination start. Default: 0. Maximum 1000.
limit: number (optional)
Number of results. Default: 200. Maximum 1000.
select: string (optional)
Field selection.
populate: string (optional)
Field population.
q: string (optional)
Text query, find query term as regex in profile.name. If q is provided, only recent conversations (last 90 days) will be returned.
conversation: string (optional)
ID of the Conversation.
organization: string (optional)
ID of the Organization.
profile.name: string (optional)
Profile attribute like name, givenName, familyName, telephone or email.
data.MyCarVIN: string (optional)
Data attribute like MyCarVIN or MyCarLicensePlate
meta: string (optional)
Meta variable.
createdBy: string (optional)
ID of the creating user.

Contact ¶

GET https://api.web1on1.chat/v2/contacts/contact_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56467a06d9b082b0059151dc",
  "organization": "5a12329862eca153b1db4354",
  "conversation": "5a1d8cd2cff15226e10e00b7",
  "blockUntil": "2016-01-07T14:03:43Z",
  "presences": [
    {
      "service": "56467a06d9b082b0059151dc",
      "remoteDeviceId": "ANgGx5u*RxqH",
      "remoteContactId": "8dPLapu2017@s1.smartsupp.com",
      "remoteRoomId": "uid3710@s1.smartsupp.com/95f217",
      "platform": "web",
      "status": "unknown",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "profile": {
    "name": "John Doe",
    "initials": "J.",
    "givenName": "John",
    "familyName": "Doe",
    "additionalName": "William",
    "honorificPrefix": "Dr.",
    "honorificSuffix": "esq.",
    "gender": "unknown",
    "address": {
      "streetAddress": "Downing street",
      "streetNumber": "10",
      "addressLocality": "London",
      "addressRegion": "London",
      "postalCode": "SW1A 2AA",
      "addressCountry": "UK"
    },
    "telephone": "+31209876543",
    "email": "john@example.com",
    "worksFor": "Acme, Inc."
  },
  "links": [
    {
      "label": "Instagram",
      "url": "https://instagr.am/49764674",
      "icon": "https://cdn.web1on1.chat/icons/instagram.png"
    }
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Contact."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Contact."
    },
    "conversation": {
      "type": "string",
      "description": "The ID of the conversation assigned to this Contact."
    },
    "blockUntil": {
      "type": "string",
      "description": "ISO8601 date and time to release any contact block (suppressing of messages)."
    },
    "presences": {
      "type": "array",
      "description": "An array of known service presences for the Contact."
    },
    "profile": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Full name of the Contact, in cases where givenName and familyName entry methods are not available."
        },
        "initials": {
          "type": "string",
          "description": "Contact initials"
        },
        "givenName": {
          "type": "string",
          "description": "Contact given name or first name"
        },
        "familyName": {
          "type": "string",
          "description": "Contact family name or surname"
        },
        "additionalName": {
          "type": "string",
          "description": "Contact middle name, if applicable"
        },
        "honorificPrefix": {
          "type": "string",
          "description": "Name prefix"
        },
        "honorificSuffix": {
          "type": "string",
          "description": "Name suffix"
        },
        "gender": {
          "type": "string",
          "enum": [
            "unknown",
            "male",
            "female",
            "indeterminate"
          ],
          "default": "unknown",
          "description": "Contact biological sex"
        },
        "address": {
          "type": "object",
          "properties": {
            "streetAddress": {
              "type": "string",
              "description": "Address street name"
            },
            "streetNumber": {
              "type": "string",
              "description": "Address street number"
            },
            "addressLocality": {
              "type": "string",
              "description": "City or town"
            },
            "addressRegion": {
              "type": "string",
              "description": "Region"
            },
            "postalCode": {
              "type": "string",
              "description": "Address location zip/postal code"
            },
            "addressCountry": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 2-letter country code of address location."
            }
          },
          "description": "Address object"
        },
        "telephone": {
          "type": "string",
          "description": "Contact telephone number"
        },
        "email": {
          "type": "string",
          "description": "Contact email address"
        },
        "worksFor": {
          "type": "string",
          "description": "Primary organization that the contact works for"
        }
      },
      "description": "Contact profile data."
    },
    "links": {
      "type": "array",
      "description": "An array of known external profile/service URLs for the Contact."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Contact was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Contact was last modified."
    }
  }
}

Retrieve a Contact
GET`/contacts/{contact_id}`

Returns a specific Contact.

URI Parameters

HideShow

contact_id: string (required)
ID of the Contact.

PATCH https://api.web1on1.chat/v2/contacts/contact_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "5a12329862eca153b1db4354",
  "conversation": "5a1d8cd2cff15226e10e00b7",
  "blockUntil": "2016-01-07T14:03:43Z",
  "presences": [
    {
      "service": "56467a06d9b082b0059151dc",
      "remoteDeviceId": "ANgGx5u*RxqH",
      "remoteContactId": "8dPLapu2017@s1.smartsupp.com",
      "remoteRoomId": "uid3710@s1.smartsupp.com/95f217",
      "platform": "web",
      "status": "unknown",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "profile": {
    "name": "John Doe",
    "initials": "J.",
    "givenName": "John",
    "familyName": "Doe",
    "additionalName": "William",
    "honorificPrefix": "Dr.",
    "honorificSuffix": "esq.",
    "gender": "unknown",
    "address": {
      "streetAddress": "Downing street",
      "streetNumber": "10",
      "addressLocality": "London",
      "addressRegion": "London",
      "postalCode": "SW1A 2AA",
      "addressCountry": "UK"
    },
    "telephone": "+31209876543",
    "email": "john@example.com",
    "worksFor": "Acme, Inc."
  },
  "links": [
    {
      "label": "Instagram",
      "url": "https://instagr.am/49764674",
      "icon": "https://cdn.web1on1.chat/icons/instagram.png"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Contact."
    },
    "conversation": {
      "type": "string",
      "description": "The ID of the conversation assigned to this Contact."
    },
    "blockUntil": {
      "type": "string",
      "description": "ISO8601 date and time to release any contact block (suppressing of messages)."
    },
    "presences": {
      "type": "array",
      "description": "An array of known service presences for the Contact."
    },
    "profile": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Full name of the Contact, in cases where givenName and familyName entry methods are not available."
        },
        "initials": {
          "type": "string",
          "description": "Contact initials"
        },
        "givenName": {
          "type": "string",
          "description": "Contact given name or first name"
        },
        "familyName": {
          "type": "string",
          "description": "Contact family name or surname"
        },
        "additionalName": {
          "type": "string",
          "description": "Contact middle name, if applicable"
        },
        "honorificPrefix": {
          "type": "string",
          "description": "Name prefix"
        },
        "honorificSuffix": {
          "type": "string",
          "description": "Name suffix"
        },
        "gender": {
          "type": "string",
          "enum": [
            "unknown",
            "male",
            "female",
            "indeterminate"
          ],
          "default": "unknown",
          "description": "Contact biological sex"
        },
        "address": {
          "type": "object",
          "properties": {
            "streetAddress": {
              "type": "string",
              "description": "Address street name"
            },
            "streetNumber": {
              "type": "string",
              "description": "Address street number"
            },
            "addressLocality": {
              "type": "string",
              "description": "City or town"
            },
            "addressRegion": {
              "type": "string",
              "description": "Region"
            },
            "postalCode": {
              "type": "string",
              "description": "Address location zip/postal code"
            },
            "addressCountry": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 2-letter country code of address location."
            }
          },
          "description": "Address object"
        },
        "telephone": {
          "type": "string",
          "description": "Contact telephone number"
        },
        "email": {
          "type": "string",
          "description": "Contact email address"
        },
        "worksFor": {
          "type": "string",
          "description": "Primary organization that the contact works for"
        }
      },
      "description": "Contact profile data."
    },
    "links": {
      "type": "array",
      "description": "An array of known external profile/service URLs for the Contact."
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56467a06d9b082b0059151dc",
  "organization": "5a12329862eca153b1db4354",
  "conversation": "5a1d8cd2cff15226e10e00b7",
  "blockUntil": "2016-01-07T14:03:43Z",
  "presences": [
    {
      "service": "56467a06d9b082b0059151dc",
      "remoteDeviceId": "ANgGx5u*RxqH",
      "remoteContactId": "8dPLapu2017@s1.smartsupp.com",
      "remoteRoomId": "uid3710@s1.smartsupp.com/95f217",
      "platform": "web",
      "status": "unknown",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "profile": {
    "name": "John Doe",
    "initials": "J.",
    "givenName": "John",
    "familyName": "Doe",
    "additionalName": "William",
    "honorificPrefix": "Dr.",
    "honorificSuffix": "esq.",
    "gender": "unknown",
    "address": {
      "streetAddress": "Downing street",
      "streetNumber": "10",
      "addressLocality": "London",
      "addressRegion": "London",
      "postalCode": "SW1A 2AA",
      "addressCountry": "UK"
    },
    "telephone": "+31209876543",
    "email": "john@example.com",
    "worksFor": "Acme, Inc."
  },
  "links": [
    {
      "label": "Instagram",
      "url": "https://instagr.am/49764674",
      "icon": "https://cdn.web1on1.chat/icons/instagram.png"
    }
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Contact."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Contact."
    },
    "conversation": {
      "type": "string",
      "description": "The ID of the conversation assigned to this Contact."
    },
    "blockUntil": {
      "type": "string",
      "description": "ISO8601 date and time to release any contact block (suppressing of messages)."
    },
    "presences": {
      "type": "array",
      "description": "An array of known service presences for the Contact."
    },
    "profile": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Full name of the Contact, in cases where givenName and familyName entry methods are not available."
        },
        "initials": {
          "type": "string",
          "description": "Contact initials"
        },
        "givenName": {
          "type": "string",
          "description": "Contact given name or first name"
        },
        "familyName": {
          "type": "string",
          "description": "Contact family name or surname"
        },
        "additionalName": {
          "type": "string",
          "description": "Contact middle name, if applicable"
        },
        "honorificPrefix": {
          "type": "string",
          "description": "Name prefix"
        },
        "honorificSuffix": {
          "type": "string",
          "description": "Name suffix"
        },
        "gender": {
          "type": "string",
          "enum": [
            "unknown",
            "male",
            "female",
            "indeterminate"
          ],
          "default": "unknown",
          "description": "Contact biological sex"
        },
        "address": {
          "type": "object",
          "properties": {
            "streetAddress": {
              "type": "string",
              "description": "Address street name"
            },
            "streetNumber": {
              "type": "string",
              "description": "Address street number"
            },
            "addressLocality": {
              "type": "string",
              "description": "City or town"
            },
            "addressRegion": {
              "type": "string",
              "description": "Region"
            },
            "postalCode": {
              "type": "string",
              "description": "Address location zip/postal code"
            },
            "addressCountry": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 2-letter country code of address location."
            }
          },
          "description": "Address object"
        },
        "telephone": {
          "type": "string",
          "description": "Contact telephone number"
        },
        "email": {
          "type": "string",
          "description": "Contact email address"
        },
        "worksFor": {
          "type": "string",
          "description": "Primary organization that the contact works for"
        }
      },
      "description": "Contact profile data."
    },
    "links": {
      "type": "array",
      "description": "An array of known external profile/service URLs for the Contact."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Contact was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Contact was last modified."
    }
  }
}

Update a Contact
PATCH`/contacts/{contact_id}`

Update a contact.

URI Parameters

HideShow

contact_id: string (required)
ID of the Contact.

Events ¶

An Event resource represents a business event, activity, incentive or happening.

Event Types ¶

An Event Type resource represents a business event, activity, incentive or happening. Its attributes are:

Property	Type	Description	Example
id	string	The unique ID of the event type.	5876bc219b9d2b54a0c464ca
organization	string	The ID of the organization that owns the event type.	5876bc219b9d2b54a0c464c9
name	string*	Name of the event type.	provider.group.action
description	string	Description of the event type.	Provider action
type	enum	Direction of event type. One of native, inbound, outbound. Defaults to inbound.	native
status	enum	Event type status. One of test, live, flagged, disabled. Defaults to test.	test
jsonata	string	JSONata expression applied to transform Event payloads.	{ “name”: “some-example.create” }
meta	MetaParams	Free-form object of key-values.	{MetaParams}
createdBy	string	The ID of the user created this bot instance	5876bc219b9d2b54a0c464c9
updatedBy	string	The ID of the user last updated this bot instance	5876bc219b9d2b54a0c464c9
createdAt	string	ISO8601 date and time of when the event type was created.	2020-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of when the event type was last modified.	2020-01-07T14:03:43Z

GET https://api.web1on1.chat/v2/eventtypes

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "5876bc219b9d2b54a0c464ca",
    "organization": "5876bc219b9d2b54a0c464c9",
    "name": "provider.group.action",
    "description": "Provider action",
    "type": "native",
    "status": "test",
    "jsonata": "{ \"name\": \"some-example.create\" }",
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "createdBy": "5876bc219b9d2b54a0c464c9",
    "updatedBy": "5876bc219b9d2b54a0c464c9",
    "createdAt": "2020-01-07T14:03:43Z",
    "updatedAt": "2020-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Event Types
GET`/eventtypes`

Return a list of all event types.

POST https://api.web1on1.chat/v2/eventtypes

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "provider.group.action",
  "description": "Provider action",
  "type": "native",
  "status": "test",
  "jsonata": "{ \"name\": \"some-example.create\" }",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the event type."
    },
    "name": {
      "type": "string",
      "description": "Name of the event type."
    },
    "description": {
      "type": "string",
      "description": "Description of the event type."
    },
    "type": {
      "type": "string",
      "enum": [
        "native",
        "inbound",
        "outbound"
      ],
      "default": "inbound",
      "description": "Direction of event type."
    },
    "status": {
      "type": "string",
      "enum": [
        "test",
        "live",
        "flagged",
        "disabled"
      ],
      "default": "test",
      "description": "Event type status."
    },
    "jsonata": {
      "type": "string",
      "description": "JSONata expression applied to transform Event payloads."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    }
  },
  "required": [
    "name"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /eventtypes/562e1085955cf08132fff510

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "provider.group.action",
  "description": "Provider action",
  "type": "native",
  "status": "test",
  "jsonata": "{ \"name\": \"some-example.create\" }",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdBy": "5876bc219b9d2b54a0c464c9",
  "updatedBy": "5876bc219b9d2b54a0c464c9",
  "createdAt": "2020-01-07T14:03:43Z",
  "updatedAt": "2020-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the event type."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the event type."
    },
    "name": {
      "type": "string",
      "description": "Name of the event type."
    },
    "description": {
      "type": "string",
      "description": "Description of the event type."
    },
    "type": {
      "type": "string",
      "enum": [
        "native",
        "inbound",
        "outbound"
      ],
      "default": "inbound",
      "description": "Direction of event type."
    },
    "status": {
      "type": "string",
      "enum": [
        "test",
        "live",
        "flagged",
        "disabled"
      ],
      "default": "test",
      "description": "Event type status."
    },
    "jsonata": {
      "type": "string",
      "description": "JSONata expression applied to transform Event payloads."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "createdBy": {
      "type": "string",
      "description": "The ID of the user created this bot instance"
    },
    "updatedBy": {
      "type": "string",
      "description": "The ID of the user last updated this bot instance"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the event type was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the event type was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Create a new Event Type
POST`/eventtypes`

Create a new event type using this action.

Event Type ¶

GET https://api.web1on1.chat/v2/eventtypes/eventtype_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "provider.group.action",
  "description": "Provider action",
  "type": "native",
  "status": "test",
  "jsonata": "{ \"name\": \"some-example.create\" }",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdBy": "5876bc219b9d2b54a0c464c9",
  "updatedBy": "5876bc219b9d2b54a0c464c9",
  "createdAt": "2020-01-07T14:03:43Z",
  "updatedAt": "2020-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the event type."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the event type."
    },
    "name": {
      "type": "string",
      "description": "Name of the event type."
    },
    "description": {
      "type": "string",
      "description": "Description of the event type."
    },
    "type": {
      "type": "string",
      "enum": [
        "native",
        "inbound",
        "outbound"
      ],
      "default": "inbound",
      "description": "Direction of event type."
    },
    "status": {
      "type": "string",
      "enum": [
        "test",
        "live",
        "flagged",
        "disabled"
      ],
      "default": "test",
      "description": "Event type status."
    },
    "jsonata": {
      "type": "string",
      "description": "JSONata expression applied to transform Event payloads."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "createdBy": {
      "type": "string",
      "description": "The ID of the user created this bot instance"
    },
    "updatedBy": {
      "type": "string",
      "description": "The ID of the user last updated this bot instance"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the event type was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the event type was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Retrieve an Event Type
GET`/eventtypes/{eventtype_id}`

Returns a specific Event Type by its ID.

URI Parameters

HideShow

eventtype_id: string (required)
ID of the Event Type.

PATCH https://api.web1on1.chat/v2/eventtypes/eventtype_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "provider.group.action",
  "description": "Provider action",
  "type": "native",
  "status": "test",
  "jsonata": "{ \"name\": \"some-example.create\" }",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the event type."
    },
    "name": {
      "type": "string",
      "description": "Name of the event type."
    },
    "description": {
      "type": "string",
      "description": "Description of the event type."
    },
    "type": {
      "type": "string",
      "enum": [
        "native",
        "inbound",
        "outbound"
      ],
      "default": "inbound",
      "description": "Direction of event type."
    },
    "status": {
      "type": "string",
      "enum": [
        "test",
        "live",
        "flagged",
        "disabled"
      ],
      "default": "test",
      "description": "Event type status."
    },
    "jsonata": {
      "type": "string",
      "description": "JSONata expression applied to transform Event payloads."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    }
  },
  "required": [
    "name"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "provider.group.action",
  "description": "Provider action",
  "type": "native",
  "status": "test",
  "jsonata": "{ \"name\": \"some-example.create\" }",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdBy": "5876bc219b9d2b54a0c464c9",
  "updatedBy": "5876bc219b9d2b54a0c464c9",
  "createdAt": "2020-01-07T14:03:43Z",
  "updatedAt": "2020-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the event type."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the event type."
    },
    "name": {
      "type": "string",
      "description": "Name of the event type."
    },
    "description": {
      "type": "string",
      "description": "Description of the event type."
    },
    "type": {
      "type": "string",
      "enum": [
        "native",
        "inbound",
        "outbound"
      ],
      "default": "inbound",
      "description": "Direction of event type."
    },
    "status": {
      "type": "string",
      "enum": [
        "test",
        "live",
        "flagged",
        "disabled"
      ],
      "default": "test",
      "description": "Event type status."
    },
    "jsonata": {
      "type": "string",
      "description": "JSONata expression applied to transform Event payloads."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "createdBy": {
      "type": "string",
      "description": "The ID of the user created this bot instance"
    },
    "updatedBy": {
      "type": "string",
      "description": "The ID of the user last updated this bot instance"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the event type was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the event type was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update an Event Type
PATCH`/eventtypes/{eventtype_id}`

Update a specific Event Type.

URI Parameters

HideShow

eventtype_id: string (required)
ID of the Event Type.

DELETE https://api.web1on1.chat/v2/eventtypes/eventtype_id

Responses204

This response has no content.

Delete an Event Type
DELETE`/eventtypes/{eventtype_id}`

Delete an Event Type.

URI Parameters

HideShow

eventtype_id: string (required)
ID of the Event Type.

Events ¶

An Event resource represents a business event, activity, incentive or happening. Its attributes are:

Property	Type	Description	Example
id	string	Unique identifier for the event	562e1085955cf08132fff510
organization	string*	Organization ID of the owning organization.	58bcbafb8547f04f68c14bdb
conversation	string*	Conversation ID.	58bc9aecd906223dcec36493
eventtype	string*	Event Type ID.	58bc9aecd906223dcec36495
name	string	Name of the event; default is copied from the event type.	Provider Group Action
payload	object*	Event payload.	{object}
meta	MetaParams	Free-form object of key-values.	{MetaParams}
updatedBy	string	User ID of the user that created or last modified the resource.	58bc9aecd906223dcec36495
createdAt	string	ISO8601 date and time of Event creation.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of Event last modification.	2016-01-07T14:03:43Z

GET https://api.web1on1.chat/v2/events

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "562e1085955cf08132fff510",
    "organization": "58bcbafb8547f04f68c14bdb",
    "conversation": "58bc9aecd906223dcec36493",
    "eventtype": "58bc9aecd906223dcec36495",
    "name": "Provider Group Action",
    "payload": {},
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "updatedBy": "58bc9aecd906223dcec36495",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Events
GET`/events`

Return a list of all events.

POST https://api.web1on1.chat/v2/events

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "conversation": "58bc9aecd906223dcec36493",
  "eventtype": "58bc9aecd906223dcec36495",
  "name": "Provider Group Action",
  "payload": {},
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "eventtype": {
      "type": "string",
      "description": "Event Type ID."
    },
    "name": {
      "type": "string",
      "description": "Name of the event; default is copied from the event type."
    },
    "payload": {
      "type": "object",
      "properties": {},
      "description": "Event payload."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource."
    }
  },
  "required": [
    "organization",
    "conversation",
    "eventtype",
    "payload"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /events/562e1085955cf08132fff510

Body

{
  "id": "562e1085955cf08132fff510",
  "organization": "58bcbafb8547f04f68c14bdb",
  "conversation": "58bc9aecd906223dcec36493",
  "eventtype": "58bc9aecd906223dcec36495",
  "name": "Provider Group Action",
  "payload": {},
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the event"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "eventtype": {
      "type": "string",
      "description": "Event Type ID."
    },
    "name": {
      "type": "string",
      "description": "Name of the event; default is copied from the event type."
    },
    "payload": {
      "type": "object",
      "properties": {},
      "description": "Event payload."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of Event creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of Event last modification."
    }
  },
  "required": [
    "organization",
    "conversation",
    "eventtype",
    "payload"
  ]
}

Create a new Event
POST`/events`

You may create a event using this action.

Event ¶

GET https://api.web1on1.chat/v2/events/event_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "562e1085955cf08132fff510",
  "organization": "58bcbafb8547f04f68c14bdb",
  "conversation": "58bc9aecd906223dcec36493",
  "eventtype": "58bc9aecd906223dcec36495",
  "name": "Provider Group Action",
  "payload": {},
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the event"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "eventtype": {
      "type": "string",
      "description": "Event Type ID."
    },
    "name": {
      "type": "string",
      "description": "Name of the event; default is copied from the event type."
    },
    "payload": {
      "type": "object",
      "properties": {},
      "description": "Event payload."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of Event creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of Event last modification."
    }
  },
  "required": [
    "organization",
    "conversation",
    "eventtype",
    "payload"
  ]
}

Retrieve an Event
GET`/events/{event_id}`

Returns a specific Event.

URI Parameters

HideShow

event_id: string (required)
ID of the Event.

PATCH https://api.web1on1.chat/v2/events/event_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "conversation": "58bc9aecd906223dcec36493",
  "eventtype": "58bc9aecd906223dcec36495",
  "name": "Provider Group Action",
  "payload": {},
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "eventtype": {
      "type": "string",
      "description": "Event Type ID."
    },
    "name": {
      "type": "string",
      "description": "Name of the event; default is copied from the event type."
    },
    "payload": {
      "type": "object",
      "properties": {},
      "description": "Event payload."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource."
    }
  },
  "required": [
    "organization",
    "conversation",
    "eventtype",
    "payload"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "562e1085955cf08132fff510",
  "organization": "58bcbafb8547f04f68c14bdb",
  "conversation": "58bc9aecd906223dcec36493",
  "eventtype": "58bc9aecd906223dcec36495",
  "name": "Provider Group Action",
  "payload": {},
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the event"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "eventtype": {
      "type": "string",
      "description": "Event Type ID."
    },
    "name": {
      "type": "string",
      "description": "Name of the event; default is copied from the event type."
    },
    "payload": {
      "type": "object",
      "properties": {},
      "description": "Event payload."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of Event creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of Event last modification."
    }
  },
  "required": [
    "organization",
    "conversation",
    "eventtype",
    "payload"
  ]
}

Update an Event
PATCH`/events/{event_id}`

Update a specific Event.

URI Parameters

HideShow

event_id: string (required)
ID of the Event.

DELETE https://api.web1on1.chat/v2/events/event_id

Responses204

This response has no content.

Delete an Event
DELETE`/events/{event_id}`

Delete an Event.

URI Parameters

HideShow

event_id: string (required)
ID of the Event.

Provisioning ¶

The Provisioning APIs provide methods for configuring primary entities in the system for proper account setup.

Users ¶

Users are people or apps that can log into Web1on1. A User resource specifies the profile, permissions, preferences and login credentials for Web1on1 agents and admin users.

A User object has the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the user.	57c8479433f5d57d3013a0bc
familyName	string	Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property.	Vries
givenName	string	Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property.	Hans
additionalName	string	An additional name for a User, can be used for a middle name.	de
displayName	string	Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName.	Hans de Vries
email	string*	Email address of the User, used to log in.	jeff@jeffdoe.com
phone	string	User telephone number.	+31209876543
password	string	Login password for the User.	z3krUt
avatar	string	Avatar URL for the User.	http://yoursite.com/images/avatar.png
organization	string	The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations.	55dcf8aa048ee2227d4aa1a4
role	enum	The role of the agent within the organization. One of agent, admin, owner. Defaults to agent.	agent
settings	Settings	User preferences.	{Settings}
meta	MetaParams	Free-form object of key-values, that will be passed on to external systems, eg in webhook data.	{MetaParams}
status	enum	The status of the user for given organization. One of queued, invited, active, archived. Defaults to queued.	queued
apiToken	string	API key for role ‘bot’ users.	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV
lastLogin	string	ISO8601 date and time of when the user last logged in.	2016-08-05T08:40:51.620Z
createdAt	string	ISO8601 date and time of when the user was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of when the user was last modified.	2016-01-07T14:03:43Z

Person name conventions are adapted from JSON-LD standards as specified by Google and described at Schema.org.

The user.settings object specifies user preferences and may have the following properties:

Property	Type	Description	Example
timezone	string	Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in.	Europe/Amsterdam
timezoneSet	boolean	Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system). Defaults to false.	false
locale	enum	ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location. One of en, nl, de, fr. Defaults to en.	en
localeSet	boolean	Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system). Defaults to false.	false
audioOnChat	boolean	Boolean to bleep on queue increments. Defaults to true.	true
audioOnMessage	boolean	Boolean to bleep on new messages. Defaults to false.	false
notifyOnChat	boolean	Boolean to show desktop notifications on queue increments. Defaults to false.	false
notifyOnMessage	boolean	Boolean to show a desktop notification on each incoming message. Defaults to false.	false
tabdotNotify	boolean	Boolean to show a browser tab notification on queued conversations. Defaults to true.	true
tabdotMessage	boolean	Boolean to show a browser tab notification on unread messages. Defaults to true.	true
pushNotify	boolean	Boolean to enable mobile push inbox notifications. Defaults to false.	false
focusOnAccept	boolean	Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents. Defaults to false.	false
notifications	array	List of notification roles for the user.	[technical]
cannedResponses	array	List of canned responses.	[What is your name?]

GET https://api.web1on1.chat/v2/users

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "57c8479433f5d57d3013a0bc",
    "familyName": "Vries",
    "givenName": "Hans",
    "additionalName": "de",
    "displayName": "Hans de Vries",
    "email": "jeff@jeffdoe.com",
    "phone": "+31209876543",
    "password": "z3krUt",
    "avatar": "http://yoursite.com/images/avatar.png",
    "organization": "55dcf8aa048ee2227d4aa1a4",
    "role": "agent",
    "settings": {
      "timezone": "Europe/Amsterdam",
      "timezoneSet": true,
      "locale": "en",
      "localeSet": true,
      "audioOnChat": true,
      "audioOnMessage": true,
      "notifyOnChat": true,
      "notifyOnMessage": true,
      "tabdotNotify": true,
      "tabdotMessage": true,
      "pushNotify": true,
      "focusOnAccept": true,
      "notifications": [
        "technical",
        "billing",
        "reporting",
        "knowledge",
        "results"
      ],
      "cannedResponses": [
        "What is your name?",
        "Thank you {{ givenName }}"
      ]
    },
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "status": "queued",
    "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV",
    "lastLogin": "2016-08-05T08:40:51.620Z",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Users
GET`/users`

Return a list of all account users (agents and admins).

POST https://api.web1on1.chat/v2/users

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http://yoursite.com/images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true,
    "tabdotNotify": true,
    "tabdotMessage": true,
    "pushNotify": true,
    "focusOnAccept": true,
    "notifications": [
      "technical",
      "billing",
      "reporting",
      "knowledge",
      "results"
    ],
    "cannedResponses": [
      "What is your name?",
      "Thank you {{ givenName }}"
    ]
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        },
        "tabdotNotify": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on queued conversations.",
          "default": true
        },
        "tabdotMessage": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on unread messages.",
          "default": true
        },
        "pushNotify": {
          "type": "boolean",
          "description": "Boolean to enable mobile push inbox notifications.",
          "default": false
        },
        "focusOnAccept": {
          "type": "boolean",
          "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
          "default": false
        },
        "notifications": {
          "type": "array",
          "description": "List of notification roles for the user."
        },
        "cannedResponses": {
          "type": "array",
          "description": "List of canned responses."
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    }
  },
  "required": [
    "email"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /users/57c8479433f5d57d3013a0bc

Body

{
  "id": "57c8479433f5d57d3013a0bc",
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http://yoursite.com/images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true,
    "tabdotNotify": true,
    "tabdotMessage": true,
    "pushNotify": true,
    "focusOnAccept": true,
    "notifications": [
      "technical",
      "billing",
      "reporting",
      "knowledge",
      "results"
    ],
    "cannedResponses": [
      "What is your name?",
      "Thank you {{ givenName }}"
    ]
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued",
  "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV",
  "lastLogin": "2016-08-05T08:40:51.620Z",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the user."
    },
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        },
        "tabdotNotify": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on queued conversations.",
          "default": true
        },
        "tabdotMessage": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on unread messages.",
          "default": true
        },
        "pushNotify": {
          "type": "boolean",
          "description": "Boolean to enable mobile push inbox notifications.",
          "default": false
        },
        "focusOnAccept": {
          "type": "boolean",
          "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
          "default": false
        },
        "notifications": {
          "type": "array",
          "description": "List of notification roles for the user."
        },
        "cannedResponses": {
          "type": "array",
          "description": "List of canned responses."
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    },
    "apiToken": {
      "type": "string",
      "description": "API key for role 'bot' users."
    },
    "lastLogin": {
      "type": "string",
      "description": "ISO8601 date and time of when the user last logged in."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was last modified."
    }
  },
  "required": [
    "email"
  ]
}

Create a New User
POST`/users`

You may create a user using this action. It takes a JSON object containing a name, email and password, and optional settings, role and/or organization.

User ¶

GET https://api.web1on1.chat/v2/users/user_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "57c8479433f5d57d3013a0bc",
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http://yoursite.com/images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true,
    "tabdotNotify": true,
    "tabdotMessage": true,
    "pushNotify": true,
    "focusOnAccept": true,
    "notifications": [
      "technical",
      "billing",
      "reporting",
      "knowledge",
      "results"
    ],
    "cannedResponses": [
      "What is your name?",
      "Thank you {{ givenName }}"
    ]
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued",
  "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV",
  "lastLogin": "2016-08-05T08:40:51.620Z",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the user."
    },
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        },
        "tabdotNotify": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on queued conversations.",
          "default": true
        },
        "tabdotMessage": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on unread messages.",
          "default": true
        },
        "pushNotify": {
          "type": "boolean",
          "description": "Boolean to enable mobile push inbox notifications.",
          "default": false
        },
        "focusOnAccept": {
          "type": "boolean",
          "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
          "default": false
        },
        "notifications": {
          "type": "array",
          "description": "List of notification roles for the user."
        },
        "cannedResponses": {
          "type": "array",
          "description": "List of canned responses."
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    },
    "apiToken": {
      "type": "string",
      "description": "API key for role 'bot' users."
    },
    "lastLogin": {
      "type": "string",
      "description": "ISO8601 date and time of when the user last logged in."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was last modified."
    }
  },
  "required": [
    "email"
  ]
}

Retrieve a User
GET`/users/{user_id}`

View a User. Get the currently authenticated User by issuing a request for GET /users/me.

URI Parameters

HideShow

user_id: number (required)
ID of the User, or the string ‘me’ to return the current user.

PATCH https://api.web1on1.chat/v2/users/user_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http://yoursite.com/images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true,
    "tabdotNotify": true,
    "tabdotMessage": true,
    "pushNotify": true,
    "focusOnAccept": true,
    "notifications": [
      "technical",
      "billing",
      "reporting",
      "knowledge",
      "results"
    ],
    "cannedResponses": [
      "What is your name?",
      "Thank you {{ givenName }}"
    ]
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        },
        "tabdotNotify": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on queued conversations.",
          "default": true
        },
        "tabdotMessage": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on unread messages.",
          "default": true
        },
        "pushNotify": {
          "type": "boolean",
          "description": "Boolean to enable mobile push inbox notifications.",
          "default": false
        },
        "focusOnAccept": {
          "type": "boolean",
          "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
          "default": false
        },
        "notifications": {
          "type": "array",
          "description": "List of notification roles for the user."
        },
        "cannedResponses": {
          "type": "array",
          "description": "List of canned responses."
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    }
  },
  "required": [
    "email"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "57c8479433f5d57d3013a0bc",
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http://yoursite.com/images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true,
    "tabdotNotify": true,
    "tabdotMessage": true,
    "pushNotify": true,
    "focusOnAccept": true,
    "notifications": [
      "technical",
      "billing",
      "reporting",
      "knowledge",
      "results"
    ],
    "cannedResponses": [
      "What is your name?",
      "Thank you {{ givenName }}"
    ]
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued",
  "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV",
  "lastLogin": "2016-08-05T08:40:51.620Z",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the user."
    },
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        },
        "tabdotNotify": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on queued conversations.",
          "default": true
        },
        "tabdotMessage": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on unread messages.",
          "default": true
        },
        "pushNotify": {
          "type": "boolean",
          "description": "Boolean to enable mobile push inbox notifications.",
          "default": false
        },
        "focusOnAccept": {
          "type": "boolean",
          "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
          "default": false
        },
        "notifications": {
          "type": "array",
          "description": "List of notification roles for the user."
        },
        "cannedResponses": {
          "type": "array",
          "description": "List of canned responses."
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    },
    "apiToken": {
      "type": "string",
      "description": "API key for role 'bot' users."
    },
    "lastLogin": {
      "type": "string",
      "description": "ISO8601 date and time of when the user last logged in."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was last modified."
    }
  },
  "required": [
    "email"
  ]
}

Update a User
PATCH`/users/{user_id}`

You may edit a user using this action. It takes a (possibly partial) JSON object containing one or more of the user attributes.

URI Parameters

HideShow

user_id: number (required)
ID of the User, or the string ‘me’ to return the current user.

GET https://api.web1on1.chat/v2/users/me/organizations

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "57c8479433f5d57d3013a0bc",
  "organizations": [
    {
      "organization": "55dcf8aa048ee2227d4aa1a4",
      "role": "agent",
      "selected": true
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the user."
    },
    "organizations": {
      "type": "array",
      "description": "A list of user organizations (boolean)."
    }
  }
}

Retrieve user organizations
GET`/users/me/organizations`

Return a list of currently authenticated user organizations.

DELETE https://api.web1on1.chat/v2/users/user_id/organizations/organization_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Remove organization from user
DELETE`/users/{user_id}/organizations/{organization_id}`

Remove user from organizations list.

URI Parameters

HideShow

user_id: string (required)
ID of the User.
organization_id: string (required)
ID of the Organization.

DELETE https://api.web1on1.chat/v2/users/user_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete a User
DELETE`/users/{user_id}`

Sets the archived bit for a User, which will prevent it from coming up in listings and search results, but will keep internal references intact to preserve system data integrity.

URI Parameters

HideShow

user_id: number (required)
ID of the User, or the string ‘me’ to return the current user.

User Avatar ¶

POST https://api.web1on1.chat/v2/users/user_id/avatar

Requestsexample 1

Headers

Content-Type: multipart/form-data;boundary=---BOUNDARY
Authorization: Bearer <token>

Body

---BOUNDARY--
Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: image/jpeg
Content-Transfer-Encoding: base64

/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIA
AhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEB
AAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AD//Z
-----BOUNDARY

Responses201

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "id": "57c8479433f5d57d3013a0bc",
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http://yoursite.com/images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true,
    "tabdotNotify": true,
    "tabdotMessage": true,
    "pushNotify": true,
    "focusOnAccept": true,
    "notifications": [
      "technical",
      "billing",
      "reporting",
      "knowledge",
      "results"
    ],
    "cannedResponses": [
      "What is your name?",
      "Thank you {{ givenName }}"
    ]
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued",
  "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV",
  "lastLogin": "2016-08-05T08:40:51.620Z",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the user."
    },
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        },
        "tabdotNotify": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on queued conversations.",
          "default": true
        },
        "tabdotMessage": {
          "type": "boolean",
          "description": "Boolean to show a browser tab notification on unread messages.",
          "default": true
        },
        "pushNotify": {
          "type": "boolean",
          "description": "Boolean to enable mobile push inbox notifications.",
          "default": false
        },
        "focusOnAccept": {
          "type": "boolean",
          "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
          "default": false
        },
        "notifications": {
          "type": "array",
          "description": "List of notification roles for the user."
        },
        "cannedResponses": {
          "type": "array",
          "description": "List of canned responses."
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    },
    "apiToken": {
      "type": "string",
      "description": "API key for role 'bot' users."
    },
    "lastLogin": {
      "type": "string",
      "description": "ISO8601 date and time of when the user last logged in."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was last modified."
    }
  },
  "required": [
    "email"
  ]
}

Upload a User Avatar
POST`/users/{user_id}/avatar`

Upload a user profile image into cloud storage. The image will be resized and cropped.

URI Parameters

HideShow

user_id: string (required)
ID of the User.

DELETE https://api.web1on1.chat/v2/users/user_id/avatar

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete the User Avatar
DELETE`/users/{user_id}/avatar`

Delete the avatar image from cloud storage and set the User’s avatar property to null.

URI Parameters

HideShow

user_id: string (required)
ID of the User.

Organizations ¶

The Organization resource represents a company on behalf of which chats are performed.

Organizations are the primary resource in the Web1on1 system. Other resources are tied to exactly one organization.

An Organization record has the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the Organization.	56467a06d9b082b0059151dc
name	string*	The name of the Organization.	Acme Inc.
displayName	string	Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name.	Acme Inc.
status	enum	Organization status. One of queued, active, pendingArchive, archived. Defaults to active.	queued
email	string	An email address for users to contact support in case of any issues with the organization.	support@example.com
url	string	The URL of the Organization’s corporate website.	https://example.com
logo	string	The URL of the Organization’s logo image.	https://example.com/logo.png
country	string	The two-letter ISO 3166 country code of the Organization’s headquarters.	NL
locale	enum	ISO 639-1 two-letter language code. One of en, nl, de, fr. Defaults to en.	en
timezone	string	Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam.	Europe/Amsterdam
industry	string	The industry the Organization is in.	automotive
settings	OrganizationSettings	Configuration settings for the organization.	{OrganizationSettings}
aliases	array	User avatars and aliases to use instead of real names.	[{Alias}]
stopwords	array	List of words that should not be used in any communication on behalf of the Organization.	[foo]
commands	array	List of custom (bot) commands that should be made available to the agent.	[intakebot]
tags	array	List of keywords/tags for the organization.	[automotive]
domainPrefix	string	The white label subdomain part for the organization.	skynet
domain	string	The white label domain for the organization.	chat.report
partners	array	Partner organizations to allow access to conversations.	[{Partner}]
whitelist	array	List of emails and domains for which agent self-registration is allowed.	[john@example.org]
defaultRole	enum	Self-registering agent role. One of guest, agent. Defaults to guest.	guest
dataRetention	DataRetention	An object specifying record expiration and purge time.	{DataRetention}
billingInfo	BillingInfo*	An object specifying the organization billing settings.	{BillingInfo}
emailAs	string	An email ‘from’ sender address for results notifications.	results@example.com
meta	MetaParams	Free-form object of key-values, that will be passed on to external systems, eg in webhook data.	{MetaParams}
createdAt	string	ISO8601 date and time of when the Organization was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of when the Organization was last modified.	2016-01-07T14:03:43Z

Settings

The settings attribute is an object specifying configuration settings for the organization.

Settings have the following properties:

Property	Type	Description	Example
routeOnReply	enum	Determines how recurring visitors to same-agent are dispatched. One of accept, assign, route. Defaults to accept.	accept
enableMail	boolean	Flag signifying if email notifications are sent to organization admins. Defaults to true.	true

BillingInfo

The billingInfo attribute specifies the billing settings for the organization.

Property	Type	Description	Example
billReceiver	string*	Organzation paying for the invoice.	{string}
billSender	string*	Organzation who is ending the invoice.	{string}
trialEndsOn	string	ISO8601 date and time of when the Organization trial has ended.	2016-01-07T14:03:43Z
stripeCustomerId	string*	Customer id in Stripe.	cus_KlieDvHuODgU3u
liveMode	boolean	Used enviroment in Stripe (development or live). Defaults to true.	true
moveToLive	boolean	Flag if organization must be moved to live enviroment in Stripe. Defaults to false.	false
w1on1ResultId	string	Alternative product id in Stripe for agent results.	{string}
daysUntilDue	number	Due days for invoicing (default 14).	14
meta	MetaParams	Free-form object of key-values.	{MetaParams}
enableMecs	boolean	Option to disable Mecs in Stripe. Defaults to false.	false
enableAmp	boolean	Option to disable AMP licence in Stripe. Defaults to false.	false
enableSepaDebitCosts	boolean	Option to disable Sepa Debit costs in Stripe. Defaults to false.	false
version	number	Billing version for that organization (can be 1 or 2)	1
currentPlan	string*	Current plan used for version 2 (can be base, grow or scale).	scale

GET https://api.web1on1.chat/v2/organizations

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "56467a06d9b082b0059151dc",
    "name": "Acme Inc.",
    "displayName": "Acme Inc.",
    "status": "queued",
    "email": "support@example.com",
    "url": "https://example.com",
    "logo": "https://example.com/logo.png",
    "country": "NL",
    "locale": "en",
    "timezone": "Europe/Amsterdam",
    "industry": "automotive",
    "settings": {
      "routeOnReply": "accept",
      "enableMail": true
    },
    "aliases": [
      {
        "name": "Alexandra",
        "avatar": "https://cdn.web1on1.chat/avatars/female/smiling"
      }
    ],
    "stopwords": [
      "foo",
      "bar"
    ],
    "commands": [
      "intakebot",
      "surveybot"
    ],
    "tags": [
      "automotive",
      "insurance"
    ],
    "domainPrefix": "skynet",
    "domain": "chat.report",
    "partners": [
      {
        "organization": "5b2bf9dd27fe8b715d64ee30",
        "permission": "guest"
      }
    ],
    "whitelist": [
      "john@example.org",
      "example.com"
    ],
    "defaultRole": "guest",
    "dataRetention": {
      "length": 18,
      "unit": "month"
    },
    "billingInfo": {
      "billReceiver": "Hello, world!",
      "billSender": "Hello, world!",
      "trialEndsOn": "2016-01-07T14:03:43Z",
      "stripeCustomerId": "cus_KlieDvHuODgU3u",
      "liveMode": true,
      "moveToLive": true,
      "w1on1ResultId": "Hello, world!",
      "daysUntilDue": 14,
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      },
      "enableMecs": true,
      "enableAmp": true,
      "enableSepaDebitCosts": true,
      "version": 1,
      "currentPlan": "scale"
    },
    "emailAs": "results@example.com",
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Organizations
GET`/organizations`

Return a list of all organizations.

POST https://api.web1on1.chat/v2/organizations

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "industry": "automotive",
  "settings": {
    "routeOnReply": "accept",
    "enableMail": true
  },
  "aliases": [
    {
      "name": "Alexandra",
      "avatar": "https://cdn.web1on1.chat/avatars/female/smiling"
    }
  ],
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "partners": [
    {
      "organization": "5b2bf9dd27fe8b715d64ee30",
      "permission": "guest"
    }
  ],
  "whitelist": [
    "john@example.org",
    "example.com"
  ],
  "defaultRole": "guest",
  "dataRetention": {
    "length": 18,
    "unit": "month"
  },
  "billingInfo": {
    "billReceiver": "Hello, world!",
    "billSender": "Hello, world!",
    "trialEndsOn": "2016-01-07T14:03:43Z",
    "stripeCustomerId": "cus_KlieDvHuODgU3u",
    "liveMode": true,
    "moveToLive": true,
    "w1on1ResultId": "Hello, world!",
    "daysUntilDue": 14,
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "enableMecs": true,
    "enableAmp": true,
    "enableSepaDebitCosts": true,
    "version": 1,
    "currentPlan": "scale"
  },
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "settings": {
      "type": "object",
      "properties": {
        "routeOnReply": {
          "type": "string",
          "enum": [
            "accept",
            "assign",
            "route"
          ],
          "default": "accept",
          "description": "Determines how recurring visitors to same-agent are dispatched."
        },
        "enableMail": {
          "type": "boolean",
          "description": "Flag signifying if email notifications are sent to organization admins.",
          "default": true
        }
      },
      "description": "Configuration settings for the organization."
    },
    "aliases": {
      "type": "array",
      "description": "User avatars and aliases to use instead of real names."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "partners": {
      "type": "array",
      "description": "Partner organizations to allow access to conversations."
    },
    "whitelist": {
      "type": "array",
      "description": "List of emails and domains for which agent self-registration is allowed."
    },
    "defaultRole": {
      "type": "string",
      "enum": [
        "guest",
        "agent"
      ],
      "default": "guest",
      "description": "Self-registering agent role."
    },
    "dataRetention": {
      "type": "object",
      "properties": {
        "length": {
          "type": "number",
          "description": "The number of units for the time interval."
        },
        "unit": {
          "type": "string",
          "enum": [
            "month",
            "year"
          ],
          "default": "month",
          "description": "The unit of time measured."
        }
      },
      "description": "An object specifying record expiration and purge time."
    },
    "billingInfo": {
      "type": "object",
      "properties": {
        "billReceiver": {
          "type": "string",
          "description": "Organzation paying for the invoice."
        },
        "billSender": {
          "type": "string",
          "description": "Organzation who is ending the invoice."
        },
        "trialEndsOn": {
          "type": "string",
          "description": "ISO8601 date and time of when the Organization trial has ended."
        },
        "stripeCustomerId": {
          "type": "string",
          "description": "Customer id in Stripe."
        },
        "liveMode": {
          "type": "boolean",
          "description": "Used enviroment in Stripe (development or live).",
          "default": true
        },
        "moveToLive": {
          "type": "boolean",
          "description": "Flag if organization must be moved to live enviroment in Stripe.",
          "default": false
        },
        "w1on1ResultId": {
          "type": "string",
          "description": "Alternative product id in Stripe for agent results."
        },
        "daysUntilDue": {
          "type": "number",
          "description": "Due days for invoicing (default 14)."
        },
        "meta": {
          "type": "object",
          "properties": {
            "someKey": {
              "type": "string",
              "description": "An example of a free-form key/value pair."
            },
            "anotherKey": {
              "type": "string",
              "description": "Another example of a free-form key/value pair."
            }
          },
          "description": "Free-form object of key-values."
        },
        "enableMecs": {
          "type": "boolean",
          "description": "Option to disable Mecs in Stripe.",
          "default": false
        },
        "enableAmp": {
          "type": "boolean",
          "description": "Option to disable AMP licence in Stripe.",
          "default": false
        },
        "enableSepaDebitCosts": {
          "type": "boolean",
          "description": "Option to disable Sepa Debit costs in Stripe.",
          "default": false
        },
        "version": {
          "type": "number",
          "description": "Billing version for that organization (can be 1 or 2)"
        },
        "currentPlan": {
          "type": "string",
          "description": "Current plan used for version 2 (can be base, grow or scale)."
        }
      },
      "required": [
        "billReceiver",
        "billSender",
        "stripeCustomerId",
        "currentPlan"
      ],
      "description": "An object specifying the organization billing settings."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    }
  },
  "required": [
    "name",
    "billingInfo"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /organizations/56467a06d9b082b0059151dc

Body

{
  "id": "56467a06d9b082b0059151dc",
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "industry": "automotive",
  "settings": {
    "routeOnReply": "accept",
    "enableMail": true
  },
  "aliases": [
    {
      "name": "Alexandra",
      "avatar": "https://cdn.web1on1.chat/avatars/female/smiling"
    }
  ],
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "partners": [
    {
      "organization": "5b2bf9dd27fe8b715d64ee30",
      "permission": "guest"
    }
  ],
  "whitelist": [
    "john@example.org",
    "example.com"
  ],
  "defaultRole": "guest",
  "dataRetention": {
    "length": 18,
    "unit": "month"
  },
  "billingInfo": {
    "billReceiver": "Hello, world!",
    "billSender": "Hello, world!",
    "trialEndsOn": "2016-01-07T14:03:43Z",
    "stripeCustomerId": "cus_KlieDvHuODgU3u",
    "liveMode": true,
    "moveToLive": true,
    "w1on1ResultId": "Hello, world!",
    "daysUntilDue": 14,
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "enableMecs": true,
    "enableAmp": true,
    "enableSepaDebitCosts": true,
    "version": 1,
    "currentPlan": "scale"
  },
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "settings": {
      "type": "object",
      "properties": {
        "routeOnReply": {
          "type": "string",
          "enum": [
            "accept",
            "assign",
            "route"
          ],
          "default": "accept",
          "description": "Determines how recurring visitors to same-agent are dispatched."
        },
        "enableMail": {
          "type": "boolean",
          "description": "Flag signifying if email notifications are sent to organization admins.",
          "default": true
        }
      },
      "description": "Configuration settings for the organization."
    },
    "aliases": {
      "type": "array",
      "description": "User avatars and aliases to use instead of real names."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "partners": {
      "type": "array",
      "description": "Partner organizations to allow access to conversations."
    },
    "whitelist": {
      "type": "array",
      "description": "List of emails and domains for which agent self-registration is allowed."
    },
    "defaultRole": {
      "type": "string",
      "enum": [
        "guest",
        "agent"
      ],
      "default": "guest",
      "description": "Self-registering agent role."
    },
    "dataRetention": {
      "type": "object",
      "properties": {
        "length": {
          "type": "number",
          "description": "The number of units for the time interval."
        },
        "unit": {
          "type": "string",
          "enum": [
            "month",
            "year"
          ],
          "default": "month",
          "description": "The unit of time measured."
        }
      },
      "description": "An object specifying record expiration and purge time."
    },
    "billingInfo": {
      "type": "object",
      "properties": {
        "billReceiver": {
          "type": "string",
          "description": "Organzation paying for the invoice."
        },
        "billSender": {
          "type": "string",
          "description": "Organzation who is ending the invoice."
        },
        "trialEndsOn": {
          "type": "string",
          "description": "ISO8601 date and time of when the Organization trial has ended."
        },
        "stripeCustomerId": {
          "type": "string",
          "description": "Customer id in Stripe."
        },
        "liveMode": {
          "type": "boolean",
          "description": "Used enviroment in Stripe (development or live).",
          "default": true
        },
        "moveToLive": {
          "type": "boolean",
          "description": "Flag if organization must be moved to live enviroment in Stripe.",
          "default": false
        },
        "w1on1ResultId": {
          "type": "string",
          "description": "Alternative product id in Stripe for agent results."
        },
        "daysUntilDue": {
          "type": "number",
          "description": "Due days for invoicing (default 14)."
        },
        "meta": {
          "type": "object",
          "properties": {
            "someKey": {
              "type": "string",
              "description": "An example of a free-form key/value pair."
            },
            "anotherKey": {
              "type": "string",
              "description": "Another example of a free-form key/value pair."
            }
          },
          "description": "Free-form object of key-values."
        },
        "enableMecs": {
          "type": "boolean",
          "description": "Option to disable Mecs in Stripe.",
          "default": false
        },
        "enableAmp": {
          "type": "boolean",
          "description": "Option to disable AMP licence in Stripe.",
          "default": false
        },
        "enableSepaDebitCosts": {
          "type": "boolean",
          "description": "Option to disable Sepa Debit costs in Stripe.",
          "default": false
        },
        "version": {
          "type": "number",
          "description": "Billing version for that organization (can be 1 or 2)"
        },
        "currentPlan": {
          "type": "string",
          "description": "Current plan used for version 2 (can be base, grow or scale)."
        }
      },
      "required": [
        "billReceiver",
        "billSender",
        "stripeCustomerId",
        "currentPlan"
      ],
      "description": "An object specifying the organization billing settings."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was last modified."
    }
  },
  "required": [
    "name",
    "billingInfo"
  ]
}

Create a New Organization
POST`/organizations`

You may create a organization using this action.

Organization ¶

GET https://api.web1on1.chat/v2/organizations/organization_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56467a06d9b082b0059151dc",
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "industry": "automotive",
  "settings": {
    "routeOnReply": "accept",
    "enableMail": true
  },
  "aliases": [
    {
      "name": "Alexandra",
      "avatar": "https://cdn.web1on1.chat/avatars/female/smiling"
    }
  ],
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "partners": [
    {
      "organization": "5b2bf9dd27fe8b715d64ee30",
      "permission": "guest"
    }
  ],
  "whitelist": [
    "john@example.org",
    "example.com"
  ],
  "defaultRole": "guest",
  "dataRetention": {
    "length": 18,
    "unit": "month"
  },
  "billingInfo": {
    "billReceiver": "Hello, world!",
    "billSender": "Hello, world!",
    "trialEndsOn": "2016-01-07T14:03:43Z",
    "stripeCustomerId": "cus_KlieDvHuODgU3u",
    "liveMode": true,
    "moveToLive": true,
    "w1on1ResultId": "Hello, world!",
    "daysUntilDue": 14,
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "enableMecs": true,
    "enableAmp": true,
    "enableSepaDebitCosts": true,
    "version": 1,
    "currentPlan": "scale"
  },
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "settings": {
      "type": "object",
      "properties": {
        "routeOnReply": {
          "type": "string",
          "enum": [
            "accept",
            "assign",
            "route"
          ],
          "default": "accept",
          "description": "Determines how recurring visitors to same-agent are dispatched."
        },
        "enableMail": {
          "type": "boolean",
          "description": "Flag signifying if email notifications are sent to organization admins.",
          "default": true
        }
      },
      "description": "Configuration settings for the organization."
    },
    "aliases": {
      "type": "array",
      "description": "User avatars and aliases to use instead of real names."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "partners": {
      "type": "array",
      "description": "Partner organizations to allow access to conversations."
    },
    "whitelist": {
      "type": "array",
      "description": "List of emails and domains for which agent self-registration is allowed."
    },
    "defaultRole": {
      "type": "string",
      "enum": [
        "guest",
        "agent"
      ],
      "default": "guest",
      "description": "Self-registering agent role."
    },
    "dataRetention": {
      "type": "object",
      "properties": {
        "length": {
          "type": "number",
          "description": "The number of units for the time interval."
        },
        "unit": {
          "type": "string",
          "enum": [
            "month",
            "year"
          ],
          "default": "month",
          "description": "The unit of time measured."
        }
      },
      "description": "An object specifying record expiration and purge time."
    },
    "billingInfo": {
      "type": "object",
      "properties": {
        "billReceiver": {
          "type": "string",
          "description": "Organzation paying for the invoice."
        },
        "billSender": {
          "type": "string",
          "description": "Organzation who is ending the invoice."
        },
        "trialEndsOn": {
          "type": "string",
          "description": "ISO8601 date and time of when the Organization trial has ended."
        },
        "stripeCustomerId": {
          "type": "string",
          "description": "Customer id in Stripe."
        },
        "liveMode": {
          "type": "boolean",
          "description": "Used enviroment in Stripe (development or live).",
          "default": true
        },
        "moveToLive": {
          "type": "boolean",
          "description": "Flag if organization must be moved to live enviroment in Stripe.",
          "default": false
        },
        "w1on1ResultId": {
          "type": "string",
          "description": "Alternative product id in Stripe for agent results."
        },
        "daysUntilDue": {
          "type": "number",
          "description": "Due days for invoicing (default 14)."
        },
        "meta": {
          "type": "object",
          "properties": {
            "someKey": {
              "type": "string",
              "description": "An example of a free-form key/value pair."
            },
            "anotherKey": {
              "type": "string",
              "description": "Another example of a free-form key/value pair."
            }
          },
          "description": "Free-form object of key-values."
        },
        "enableMecs": {
          "type": "boolean",
          "description": "Option to disable Mecs in Stripe.",
          "default": false
        },
        "enableAmp": {
          "type": "boolean",
          "description": "Option to disable AMP licence in Stripe.",
          "default": false
        },
        "enableSepaDebitCosts": {
          "type": "boolean",
          "description": "Option to disable Sepa Debit costs in Stripe.",
          "default": false
        },
        "version": {
          "type": "number",
          "description": "Billing version for that organization (can be 1 or 2)"
        },
        "currentPlan": {
          "type": "string",
          "description": "Current plan used for version 2 (can be base, grow or scale)."
        }
      },
      "required": [
        "billReceiver",
        "billSender",
        "stripeCustomerId",
        "currentPlan"
      ],
      "description": "An object specifying the organization billing settings."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was last modified."
    }
  },
  "required": [
    "name",
    "billingInfo"
  ]
}

Retrieve an Organization
GET`/organizations/{organization_id}`

Returns a specific Organization.

URI Parameters

HideShow

organization_id: string (required)
ID of the Organization.

PATCH https://api.web1on1.chat/v2/organizations/organization_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "industry": "automotive",
  "settings": {
    "routeOnReply": "accept",
    "enableMail": true
  },
  "aliases": [
    {
      "name": "Alexandra",
      "avatar": "https://cdn.web1on1.chat/avatars/female/smiling"
    }
  ],
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "partners": [
    {
      "organization": "5b2bf9dd27fe8b715d64ee30",
      "permission": "guest"
    }
  ],
  "whitelist": [
    "john@example.org",
    "example.com"
  ],
  "defaultRole": "guest",
  "dataRetention": {
    "length": 18,
    "unit": "month"
  },
  "billingInfo": {
    "billReceiver": "Hello, world!",
    "billSender": "Hello, world!",
    "trialEndsOn": "2016-01-07T14:03:43Z",
    "stripeCustomerId": "cus_KlieDvHuODgU3u",
    "liveMode": true,
    "moveToLive": true,
    "w1on1ResultId": "Hello, world!",
    "daysUntilDue": 14,
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "enableMecs": true,
    "enableAmp": true,
    "enableSepaDebitCosts": true,
    "version": 1,
    "currentPlan": "scale"
  },
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "settings": {
      "type": "object",
      "properties": {
        "routeOnReply": {
          "type": "string",
          "enum": [
            "accept",
            "assign",
            "route"
          ],
          "default": "accept",
          "description": "Determines how recurring visitors to same-agent are dispatched."
        },
        "enableMail": {
          "type": "boolean",
          "description": "Flag signifying if email notifications are sent to organization admins.",
          "default": true
        }
      },
      "description": "Configuration settings for the organization."
    },
    "aliases": {
      "type": "array",
      "description": "User avatars and aliases to use instead of real names."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "partners": {
      "type": "array",
      "description": "Partner organizations to allow access to conversations."
    },
    "whitelist": {
      "type": "array",
      "description": "List of emails and domains for which agent self-registration is allowed."
    },
    "defaultRole": {
      "type": "string",
      "enum": [
        "guest",
        "agent"
      ],
      "default": "guest",
      "description": "Self-registering agent role."
    },
    "dataRetention": {
      "type": "object",
      "properties": {
        "length": {
          "type": "number",
          "description": "The number of units for the time interval."
        },
        "unit": {
          "type": "string",
          "enum": [
            "month",
            "year"
          ],
          "default": "month",
          "description": "The unit of time measured."
        }
      },
      "description": "An object specifying record expiration and purge time."
    },
    "billingInfo": {
      "type": "object",
      "properties": {
        "billReceiver": {
          "type": "string",
          "description": "Organzation paying for the invoice."
        },
        "billSender": {
          "type": "string",
          "description": "Organzation who is ending the invoice."
        },
        "trialEndsOn": {
          "type": "string",
          "description": "ISO8601 date and time of when the Organization trial has ended."
        },
        "stripeCustomerId": {
          "type": "string",
          "description": "Customer id in Stripe."
        },
        "liveMode": {
          "type": "boolean",
          "description": "Used enviroment in Stripe (development or live).",
          "default": true
        },
        "moveToLive": {
          "type": "boolean",
          "description": "Flag if organization must be moved to live enviroment in Stripe.",
          "default": false
        },
        "w1on1ResultId": {
          "type": "string",
          "description": "Alternative product id in Stripe for agent results."
        },
        "daysUntilDue": {
          "type": "number",
          "description": "Due days for invoicing (default 14)."
        },
        "meta": {
          "type": "object",
          "properties": {
            "someKey": {
              "type": "string",
              "description": "An example of a free-form key/value pair."
            },
            "anotherKey": {
              "type": "string",
              "description": "Another example of a free-form key/value pair."
            }
          },
          "description": "Free-form object of key-values."
        },
        "enableMecs": {
          "type": "boolean",
          "description": "Option to disable Mecs in Stripe.",
          "default": false
        },
        "enableAmp": {
          "type": "boolean",
          "description": "Option to disable AMP licence in Stripe.",
          "default": false
        },
        "enableSepaDebitCosts": {
          "type": "boolean",
          "description": "Option to disable Sepa Debit costs in Stripe.",
          "default": false
        },
        "version": {
          "type": "number",
          "description": "Billing version for that organization (can be 1 or 2)"
        },
        "currentPlan": {
          "type": "string",
          "description": "Current plan used for version 2 (can be base, grow or scale)."
        }
      },
      "required": [
        "billReceiver",
        "billSender",
        "stripeCustomerId",
        "currentPlan"
      ],
      "description": "An object specifying the organization billing settings."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    }
  },
  "required": [
    "name",
    "billingInfo"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56467a06d9b082b0059151dc",
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "industry": "automotive",
  "settings": {
    "routeOnReply": "accept",
    "enableMail": true
  },
  "aliases": [
    {
      "name": "Alexandra",
      "avatar": "https://cdn.web1on1.chat/avatars/female/smiling"
    }
  ],
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "partners": [
    {
      "organization": "5b2bf9dd27fe8b715d64ee30",
      "permission": "guest"
    }
  ],
  "whitelist": [
    "john@example.org",
    "example.com"
  ],
  "defaultRole": "guest",
  "dataRetention": {
    "length": 18,
    "unit": "month"
  },
  "billingInfo": {
    "billReceiver": "Hello, world!",
    "billSender": "Hello, world!",
    "trialEndsOn": "2016-01-07T14:03:43Z",
    "stripeCustomerId": "cus_KlieDvHuODgU3u",
    "liveMode": true,
    "moveToLive": true,
    "w1on1ResultId": "Hello, world!",
    "daysUntilDue": 14,
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "enableMecs": true,
    "enableAmp": true,
    "enableSepaDebitCosts": true,
    "version": 1,
    "currentPlan": "scale"
  },
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "settings": {
      "type": "object",
      "properties": {
        "routeOnReply": {
          "type": "string",
          "enum": [
            "accept",
            "assign",
            "route"
          ],
          "default": "accept",
          "description": "Determines how recurring visitors to same-agent are dispatched."
        },
        "enableMail": {
          "type": "boolean",
          "description": "Flag signifying if email notifications are sent to organization admins.",
          "default": true
        }
      },
      "description": "Configuration settings for the organization."
    },
    "aliases": {
      "type": "array",
      "description": "User avatars and aliases to use instead of real names."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "partners": {
      "type": "array",
      "description": "Partner organizations to allow access to conversations."
    },
    "whitelist": {
      "type": "array",
      "description": "List of emails and domains for which agent self-registration is allowed."
    },
    "defaultRole": {
      "type": "string",
      "enum": [
        "guest",
        "agent"
      ],
      "default": "guest",
      "description": "Self-registering agent role."
    },
    "dataRetention": {
      "type": "object",
      "properties": {
        "length": {
          "type": "number",
          "description": "The number of units for the time interval."
        },
        "unit": {
          "type": "string",
          "enum": [
            "month",
            "year"
          ],
          "default": "month",
          "description": "The unit of time measured."
        }
      },
      "description": "An object specifying record expiration and purge time."
    },
    "billingInfo": {
      "type": "object",
      "properties": {
        "billReceiver": {
          "type": "string",
          "description": "Organzation paying for the invoice."
        },
        "billSender": {
          "type": "string",
          "description": "Organzation who is ending the invoice."
        },
        "trialEndsOn": {
          "type": "string",
          "description": "ISO8601 date and time of when the Organization trial has ended."
        },
        "stripeCustomerId": {
          "type": "string",
          "description": "Customer id in Stripe."
        },
        "liveMode": {
          "type": "boolean",
          "description": "Used enviroment in Stripe (development or live).",
          "default": true
        },
        "moveToLive": {
          "type": "boolean",
          "description": "Flag if organization must be moved to live enviroment in Stripe.",
          "default": false
        },
        "w1on1ResultId": {
          "type": "string",
          "description": "Alternative product id in Stripe for agent results."
        },
        "daysUntilDue": {
          "type": "number",
          "description": "Due days for invoicing (default 14)."
        },
        "meta": {
          "type": "object",
          "properties": {
            "someKey": {
              "type": "string",
              "description": "An example of a free-form key/value pair."
            },
            "anotherKey": {
              "type": "string",
              "description": "Another example of a free-form key/value pair."
            }
          },
          "description": "Free-form object of key-values."
        },
        "enableMecs": {
          "type": "boolean",
          "description": "Option to disable Mecs in Stripe.",
          "default": false
        },
        "enableAmp": {
          "type": "boolean",
          "description": "Option to disable AMP licence in Stripe.",
          "default": false
        },
        "enableSepaDebitCosts": {
          "type": "boolean",
          "description": "Option to disable Sepa Debit costs in Stripe.",
          "default": false
        },
        "version": {
          "type": "number",
          "description": "Billing version for that organization (can be 1 or 2)"
        },
        "currentPlan": {
          "type": "string",
          "description": "Current plan used for version 2 (can be base, grow or scale)."
        }
      },
      "required": [
        "billReceiver",
        "billSender",
        "stripeCustomerId",
        "currentPlan"
      ],
      "description": "An object specifying the organization billing settings."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was last modified."
    }
  },
  "required": [
    "name",
    "billingInfo"
  ]
}

Update an Organization
PATCH`/organizations/{organization_id}`

Update a specific Organization.

URI Parameters

HideShow

organization_id: string (required)
ID of the Organization.

DELETE https://api.web1on1.chat/v2/organizations/organization_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete an Organization
DELETE`/organizations/{organization_id}`

Delete an Organization. This method can only be called by a master Organization holder. It returns the deleted Organization on success.

URI Parameters

HideShow

organization_id: string (required)
ID of the Organization.

Organization Logo ¶

POST https://api.web1on1.chat/v2/organizations/organization_id/logo

Requestsexample 1

Headers

Content-Type: multipart/form-data;boundary=---BOUNDARY
Authorization: Bearer <token>

Body

---BOUNDARY--
Content-Disposition: form-data; name="file"; filename="logo.png"
Content-Type: image/png
Content-Transfer-Encoding: base64

/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIA
AhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEB
AAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AD//Z
-----BOUNDARY

Responses201

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "id": "56467a06d9b082b0059151dc",
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "industry": "automotive",
  "settings": {
    "routeOnReply": "accept",
    "enableMail": true
  },
  "aliases": [
    {
      "name": "Alexandra",
      "avatar": "https://cdn.web1on1.chat/avatars/female/smiling"
    }
  ],
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "partners": [
    {
      "organization": "5b2bf9dd27fe8b715d64ee30",
      "permission": "guest"
    }
  ],
  "whitelist": [
    "john@example.org",
    "example.com"
  ],
  "defaultRole": "guest",
  "dataRetention": {
    "length": 18,
    "unit": "month"
  },
  "billingInfo": {
    "billReceiver": "Hello, world!",
    "billSender": "Hello, world!",
    "trialEndsOn": "2016-01-07T14:03:43Z",
    "stripeCustomerId": "cus_KlieDvHuODgU3u",
    "liveMode": true,
    "moveToLive": true,
    "w1on1ResultId": "Hello, world!",
    "daysUntilDue": 14,
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "enableMecs": true,
    "enableAmp": true,
    "enableSepaDebitCosts": true,
    "version": 1,
    "currentPlan": "scale"
  },
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "settings": {
      "type": "object",
      "properties": {
        "routeOnReply": {
          "type": "string",
          "enum": [
            "accept",
            "assign",
            "route"
          ],
          "default": "accept",
          "description": "Determines how recurring visitors to same-agent are dispatched."
        },
        "enableMail": {
          "type": "boolean",
          "description": "Flag signifying if email notifications are sent to organization admins.",
          "default": true
        }
      },
      "description": "Configuration settings for the organization."
    },
    "aliases": {
      "type": "array",
      "description": "User avatars and aliases to use instead of real names."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "partners": {
      "type": "array",
      "description": "Partner organizations to allow access to conversations."
    },
    "whitelist": {
      "type": "array",
      "description": "List of emails and domains for which agent self-registration is allowed."
    },
    "defaultRole": {
      "type": "string",
      "enum": [
        "guest",
        "agent"
      ],
      "default": "guest",
      "description": "Self-registering agent role."
    },
    "dataRetention": {
      "type": "object",
      "properties": {
        "length": {
          "type": "number",
          "description": "The number of units for the time interval."
        },
        "unit": {
          "type": "string",
          "enum": [
            "month",
            "year"
          ],
          "default": "month",
          "description": "The unit of time measured."
        }
      },
      "description": "An object specifying record expiration and purge time."
    },
    "billingInfo": {
      "type": "object",
      "properties": {
        "billReceiver": {
          "type": "string",
          "description": "Organzation paying for the invoice."
        },
        "billSender": {
          "type": "string",
          "description": "Organzation who is ending the invoice."
        },
        "trialEndsOn": {
          "type": "string",
          "description": "ISO8601 date and time of when the Organization trial has ended."
        },
        "stripeCustomerId": {
          "type": "string",
          "description": "Customer id in Stripe."
        },
        "liveMode": {
          "type": "boolean",
          "description": "Used enviroment in Stripe (development or live).",
          "default": true
        },
        "moveToLive": {
          "type": "boolean",
          "description": "Flag if organization must be moved to live enviroment in Stripe.",
          "default": false
        },
        "w1on1ResultId": {
          "type": "string",
          "description": "Alternative product id in Stripe for agent results."
        },
        "daysUntilDue": {
          "type": "number",
          "description": "Due days for invoicing (default 14)."
        },
        "meta": {
          "type": "object",
          "properties": {
            "someKey": {
              "type": "string",
              "description": "An example of a free-form key/value pair."
            },
            "anotherKey": {
              "type": "string",
              "description": "Another example of a free-form key/value pair."
            }
          },
          "description": "Free-form object of key-values."
        },
        "enableMecs": {
          "type": "boolean",
          "description": "Option to disable Mecs in Stripe.",
          "default": false
        },
        "enableAmp": {
          "type": "boolean",
          "description": "Option to disable AMP licence in Stripe.",
          "default": false
        },
        "enableSepaDebitCosts": {
          "type": "boolean",
          "description": "Option to disable Sepa Debit costs in Stripe.",
          "default": false
        },
        "version": {
          "type": "number",
          "description": "Billing version for that organization (can be 1 or 2)"
        },
        "currentPlan": {
          "type": "string",
          "description": "Current plan used for version 2 (can be base, grow or scale)."
        }
      },
      "required": [
        "billReceiver",
        "billSender",
        "stripeCustomerId",
        "currentPlan"
      ],
      "description": "An object specifying the organization billing settings."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was last modified."
    }
  },
  "required": [
    "name",
    "billingInfo"
  ]
}

Upload an Organization Logo
POST`/organizations/{organization_id}/logo`

Upload an organization logo into Cloud Storage. The image, of format JPEG, GIF or PNG, should be a square with a minimum width and height of 200 pixels. It will be resized and cropped into various dimensions.

URI Parameters

HideShow

organization_id: string (required)
ID of the Organization.

DELETE https://api.web1on1.chat/v2/organizations/organization_id/logo

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete the Organization Logo
DELETE`/organizations/{organization_id}/logo`

Delete the logo image from cloud storage and set the Organization’s logo property to null.

URI Parameters

HideShow

organization_id: string (required)
ID of the Organization.

Organization Workflows ¶

GET https://api.web1on1.chat/v2/organizations/organization_id/workflows

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "56467a06d9b082b0059151dc",
    "organization": "58bcbafb8547f04f68c14bdb",
    "name": "Automotive - Generic",
    "enabled": true,
    "rules": [
      {
        "id": "58bc9aecd906223dcec36493",
        "conditions": {
          "any": [
            {
              "fact": "conversation.category",
              "operator": "match",
              "value": "Used Car",
              "path": ".meta"
            }
          ],
          "all": [
            {
              "fact": "conversation.category",
              "operator": "match",
              "value": "Used Car",
              "path": ".meta"
            }
          ]
        },
        "event": {
          "type": "enqueue",
          "params": {
            "name": "Sales",
            "channel": "58bc9aecd906223dcec36493",
            "delay": 20
          }
        },
        "priority": 1
      }
    ],
    "organizations": [
      "58bc9aecd906223dcec36495",
      "58bc9aecd906223dcec36493"
    ],
    "organizationTags": [
      "56467a06d9b082b0059151dc"
    ],
    "createdAt": "2017-01-07T14:03:43Z",
    "updatedAt": "2017-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Retrieve all Organization Workflows
GET`/organizations/{organization_id}/workflows`

Returns all workflow objects that are triggered for an Organization. This method returns the workflows that run for an organization across the entire organization tree, and is useful for rule testing.

URI Parameters

HideShow

organization_id: string (required)
ID of the Organization.

Organization Groups ¶

Organizations may be grouped into Organization Groups. They work like tags - each organization can be a member of multiple groups.

An Organization Group has the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the Organization Group.	5877a5ecb6b1bc76263e0a85
name	string*	The name of the Organization Group.	Realtors
organization	string	The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations.	55dcf8aa048ee2227d4aa1a4
members	array	List of Organization IDs that are a member of this group.	[5877a4a9b6b1bc76263e0a83]
createdAt	string	ISO8601 date and time of when the Organization Group was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of when the Organization Group was last modified.	2016-01-07T14:03:43Z

GET https://api.web1on1.chat/v2/orggroups

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "5877a5ecb6b1bc76263e0a85",
    "name": "Realtors",
    "organization": "55dcf8aa048ee2227d4aa1a4",
    "members": [
      "5877a4a9b6b1bc76263e0a83",
      "5877a4cbb6b1bc76263e0a84"
    ],
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Organization Groups
GET`/orggroups`

Return a list of all Organization Groups.

POST https://api.web1on1.chat/v2/orggroups

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "name": "Realtors",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    "5877a4a9b6b1bc76263e0a83",
    "5877a4cbb6b1bc76263e0a84"
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Organization Group."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "List of Organization IDs that are a member of this group."
    }
  },
  "required": [
    "name"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /orggroups/5877a5ecb6b1bc76263e0a85

Body

{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "Realtors",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    "5877a4a9b6b1bc76263e0a83",
    "5877a4cbb6b1bc76263e0a84"
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization Group."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization Group."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "List of Organization IDs that are a member of this group."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Create a New Organization Group
POST`/orggroups`

You may create a organization group using this action.

Organization Group ¶

GET https://api.web1on1.chat/v2/orggroups/group_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "Realtors",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    "5877a4a9b6b1bc76263e0a83",
    "5877a4cbb6b1bc76263e0a84"
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization Group."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization Group."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "List of Organization IDs that are a member of this group."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Retrieve an Organization Group
GET`/orggroups/{group_id}`

Returns a specific Organization Group.

URI Parameters

HideShow

group_id: string (required)
ID of the Organization Group.

PATCH https://api.web1on1.chat/v2/orggroups/group_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "name": "Realtors",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    "5877a4a9b6b1bc76263e0a83",
    "5877a4cbb6b1bc76263e0a84"
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Organization Group."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "List of Organization IDs that are a member of this group."
    }
  },
  "required": [
    "name"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "Realtors",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    "5877a4a9b6b1bc76263e0a83",
    "5877a4cbb6b1bc76263e0a84"
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization Group."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization Group."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "List of Organization IDs that are a member of this group."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update an Organization Group
PATCH`/orggroups/{group_id}`

Update a specific Organization Group.

URI Parameters

HideShow

group_id: string (required)
ID of the Organization Group.

DELETE https://api.web1on1.chat/v2/orggroups/group_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete an Organization Group
DELETE`/orggroups/{group_id}`

Delete an Organization Group.

URI Parameters

HideShow

group_id: string (required)
ID of the Organization Group.

GET https://api.web1on1.chat/v2/orggroups/group_id/members

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  "5877a4a9b6b1bc76263e0a83",
  "5877a4cbb6b1bc76263e0a84"
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Retrieve all Organization Group members
GET`/orggroups/{group_id}/members`

Returns all organization IDs that are a member of a specific Organization Group.

URI Parameters

HideShow

group_id: string (required)
ID of the Organization Group.

POST https://api.web1on1.chat/v2/orggroups/group_id/members

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

[
  "5877a4a9b6b1bc76263e0a83",
  "5877a4cbb6b1bc76263e0a84"
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Responses201

Headers

Content-Type: application/json
Location: /orggroups/5877a5ecb6b1bc76263e0a85

Body

[
  "5877a4a9b6b1bc76263e0a83",
  "5877a4cbb6b1bc76263e0a84"
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Add organizations to a Group
POST`/orggroups/{group_id}/members`

You may add one or more member organizations to an Organization Group using this action.

URI Parameters

HideShow

group_id: string (required)
ID of the Organization Group.

DELETE https://api.web1on1.chat/v2/orggroups/group_id/members/member_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Remove an organization from a Group
DELETE`/orggroups/{group_id}/members/{member_id}`

Remove a member organization from an Organization Group.

URI Parameters

HideShow

group_id: string (required)
ID of the Organization Group.
member_id: string (required)
ID of the Organization.

Bots ¶

Bot objects have the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the Bot.	5876bc219b9d2b54a0c464ca
organization	string	The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations.	5876bc219b9d2b54a0c464c9
name	string*	Name of the Bot.	BusyBot
description	string	Description of the bot.	This is the test bot
status	enum	Bot status One of inactive, active, archived. Defaults to active.	inactive
roles	array*	Bot roles Defaults to bot.	[bot]
audience	enum	The organization(s) this bot is shared with. One of global, owner, group. Defaults to owner.	global
tags	array	Sharing tags	[automotive]
avatar	string	Bot avatar url (45x45 px)	https://yoursite.com/bot.png
commands	array	Bot commands made available in the UI.	[start]
meta	MetaParams	Free-form object of key-values.

status. | {MetaParams} | | secret | string | Authentication secret for the User. | z3krUt || Property | Type | Description | Example | |—|---|—|---| | createdBy | string | The ID of the user created this bot | 5876bc219b9d2b54a0c464c9 | | updatedBy | string | The ID of the user last updated this bot | 5876bc219b9d2b54a0c464c9 | | createdAt | string | ISO8601 date and time of when the Bot was created. | 2020-01-07T14:03:43Z | | updatedAt | string | ISO8601 date and time of when the Bot was last modified. | 2020-01-07T14:03:43Z |

GET https://api.web1on1.chat/v2/bots

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "5876bc219b9d2b54a0c464ca",
    "organization": "5876bc219b9d2b54a0c464c9",
    "name": "BusyBot",
    "description": "This is the test bot",
    "status": "inactive",
    "roles": [
      "bot",
      "agent",
      "admin",
      "contact"
    ],
    "audience": "global",
    "tags": [
      "automotive",
      "realestate"
    ],
    "avatar": "https://yoursite.com/bot.png",
    "commands": [
      "start",
      "stop",
      "help"
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "secret": "z3krUt",
    "createdBy": "5876bc219b9d2b54a0c464c9",
    "updatedBy": "5876bc219b9d2b54a0c464c9",
    "createdAt": "2020-01-07T14:03:43Z",
    "updatedAt": "2020-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Bots
GET`/bots`

Return a list of all bots.

POST https://api.web1on1.chat/v2/bots

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "BusyBot",
  "description": "This is the test bot",
  "status": "inactive",
  "roles": [
    "bot",
    "agent",
    "admin",
    "contact"
  ],
  "audience": "global",
  "tags": [
    "automotive",
    "realestate"
  ],
  "avatar": "https://yoursite.com/bot.png",
  "commands": [
    "start",
    "stop",
    "help"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the Bot."
    },
    "description": {
      "type": "string",
      "description": "Description of the bot."
    },
    "status": {
      "type": "string",
      "enum": [
        "inactive",
        "active",
        "archived"
      ],
      "default": "active",
      "description": "Bot status"
    },
    "roles": {
      "type": "array",
      "default": [
        "bot"
      ],
      "description": "Bot roles"
    },
    "audience": {
      "type": "string",
      "enum": [
        "global",
        "owner",
        "group"
      ],
      "default": "owner",
      "description": "The organization(s) this bot is shared with."
    },
    "tags": {
      "type": "array",
      "description": "Sharing tags"
    },
    "avatar": {
      "type": "string",
      "description": "Bot avatar url (45x45 px)"
    },
    "commands": {
      "type": "array",
      "description": "Bot commands made available in the UI."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values.\n\nstatus."
    }
  },
  "required": [
    "name",
    "roles"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /bots/5876bc219b9d2b54a0c464ca

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "BusyBot",
  "description": "This is the test bot",
  "status": "inactive",
  "roles": [
    "bot",
    "agent",
    "admin",
    "contact"
  ],
  "audience": "global",
  "tags": [
    "automotive",
    "realestate"
  ],
  "avatar": "https://yoursite.com/bot.png",
  "commands": [
    "start",
    "stop",
    "help"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "secret": "z3krUt",
  "createdBy": "5876bc219b9d2b54a0c464c9",
  "updatedBy": "5876bc219b9d2b54a0c464c9",
  "createdAt": "2020-01-07T14:03:43Z",
  "updatedAt": "2020-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Bot."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the Bot."
    },
    "description": {
      "type": "string",
      "description": "Description of the bot."
    },
    "status": {
      "type": "string",
      "enum": [
        "inactive",
        "active",
        "archived"
      ],
      "default": "active",
      "description": "Bot status"
    },
    "roles": {
      "type": "array",
      "default": [
        "bot"
      ],
      "description": "Bot roles"
    },
    "audience": {
      "type": "string",
      "enum": [
        "global",
        "owner",
        "group"
      ],
      "default": "owner",
      "description": "The organization(s) this bot is shared with."
    },
    "tags": {
      "type": "array",
      "description": "Sharing tags"
    },
    "avatar": {
      "type": "string",
      "description": "Bot avatar url (45x45 px)"
    },
    "commands": {
      "type": "array",
      "description": "Bot commands made available in the UI."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values.\n\nstatus."
    },
    "secret": {
      "type": "string",
      "description": "Authentication secret for the User."
    },
    "createdBy": {
      "type": "string",
      "description": "The ID of the user created this bot"
    },
    "updatedBy": {
      "type": "string",
      "description": "The ID of the user last updated this bot"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Bot was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Bot was last modified."
    }
  },
  "required": [
    "name",
    "roles"
  ]
}

Create a New Bot
POST`/bots`

You can create a Bot using this action.

Bot ¶

GET https://api.web1on1.chat/v2/bots/bot_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "BusyBot",
  "description": "This is the test bot",
  "status": "inactive",
  "roles": [
    "bot",
    "agent",
    "admin",
    "contact"
  ],
  "audience": "global",
  "tags": [
    "automotive",
    "realestate"
  ],
  "avatar": "https://yoursite.com/bot.png",
  "commands": [
    "start",
    "stop",
    "help"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "secret": "z3krUt",
  "createdBy": "5876bc219b9d2b54a0c464c9",
  "updatedBy": "5876bc219b9d2b54a0c464c9",
  "createdAt": "2020-01-07T14:03:43Z",
  "updatedAt": "2020-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Bot."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the Bot."
    },
    "description": {
      "type": "string",
      "description": "Description of the bot."
    },
    "status": {
      "type": "string",
      "enum": [
        "inactive",
        "active",
        "archived"
      ],
      "default": "active",
      "description": "Bot status"
    },
    "roles": {
      "type": "array",
      "default": [
        "bot"
      ],
      "description": "Bot roles"
    },
    "audience": {
      "type": "string",
      "enum": [
        "global",
        "owner",
        "group"
      ],
      "default": "owner",
      "description": "The organization(s) this bot is shared with."
    },
    "tags": {
      "type": "array",
      "description": "Sharing tags"
    },
    "avatar": {
      "type": "string",
      "description": "Bot avatar url (45x45 px)"
    },
    "commands": {
      "type": "array",
      "description": "Bot commands made available in the UI."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values.\n\nstatus."
    },
    "secret": {
      "type": "string",
      "description": "Authentication secret for the User."
    },
    "createdBy": {
      "type": "string",
      "description": "The ID of the user created this bot"
    },
    "updatedBy": {
      "type": "string",
      "description": "The ID of the user last updated this bot"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Bot was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Bot was last modified."
    }
  },
  "required": [
    "name",
    "roles"
  ]
}

Retrieve a Bot
GET`/bots/{bot_id}`

Returns a specific Bot.

URI Parameters

HideShow

bot_id: string (required)
ID of the Bot.

PATCH https://api.web1on1.chat/v2/bots/bot_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "BusyBot",
  "description": "This is the test bot",
  "status": "inactive",
  "roles": [
    "bot",
    "agent",
    "admin",
    "contact"
  ],
  "audience": "global",
  "tags": [
    "automotive",
    "realestate"
  ],
  "avatar": "https://yoursite.com/bot.png",
  "commands": [
    "start",
    "stop",
    "help"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "secret": "z3krUt"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the Bot."
    },
    "description": {
      "type": "string",
      "description": "Description of the bot."
    },
    "status": {
      "type": "string",
      "enum": [
        "inactive",
        "active",
        "archived"
      ],
      "default": "active",
      "description": "Bot status"
    },
    "roles": {
      "type": "array",
      "default": [
        "bot"
      ],
      "description": "Bot roles"
    },
    "audience": {
      "type": "string",
      "enum": [
        "global",
        "owner",
        "group"
      ],
      "default": "owner",
      "description": "The organization(s) this bot is shared with."
    },
    "tags": {
      "type": "array",
      "description": "Sharing tags"
    },
    "avatar": {
      "type": "string",
      "description": "Bot avatar url (45x45 px)"
    },
    "commands": {
      "type": "array",
      "description": "Bot commands made available in the UI."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values.\n\nstatus."
    },
    "secret": {
      "type": "string",
      "description": "Authentication secret for the User."
    }
  },
  "required": [
    "name",
    "roles"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "BusyBot",
  "description": "This is the test bot",
  "status": "inactive",
  "roles": [
    "bot",
    "agent",
    "admin",
    "contact"
  ],
  "audience": "global",
  "tags": [
    "automotive",
    "realestate"
  ],
  "avatar": "https://yoursite.com/bot.png",
  "commands": [
    "start",
    "stop",
    "help"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "secret": "z3krUt",
  "createdBy": "5876bc219b9d2b54a0c464c9",
  "updatedBy": "5876bc219b9d2b54a0c464c9",
  "createdAt": "2020-01-07T14:03:43Z",
  "updatedAt": "2020-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Bot."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the Bot."
    },
    "description": {
      "type": "string",
      "description": "Description of the bot."
    },
    "status": {
      "type": "string",
      "enum": [
        "inactive",
        "active",
        "archived"
      ],
      "default": "active",
      "description": "Bot status"
    },
    "roles": {
      "type": "array",
      "default": [
        "bot"
      ],
      "description": "Bot roles"
    },
    "audience": {
      "type": "string",
      "enum": [
        "global",
        "owner",
        "group"
      ],
      "default": "owner",
      "description": "The organization(s) this bot is shared with."
    },
    "tags": {
      "type": "array",
      "description": "Sharing tags"
    },
    "avatar": {
      "type": "string",
      "description": "Bot avatar url (45x45 px)"
    },
    "commands": {
      "type": "array",
      "description": "Bot commands made available in the UI."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values.\n\nstatus."
    },
    "secret": {
      "type": "string",
      "description": "Authentication secret for the User."
    },
    "createdBy": {
      "type": "string",
      "description": "The ID of the user created this bot"
    },
    "updatedBy": {
      "type": "string",
      "description": "The ID of the user last updated this bot"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Bot was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Bot was last modified."
    }
  },
  "required": [
    "name",
    "roles"
  ]
}

Update a Bot
PATCH`/bots/{bot_id}`

Update a Bot using this call.

URI Parameters

HideShow

bot_id: string (required)
ID of the Bot.

DELETE https://api.web1on1.chat/v2/bots/bot_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete a Bot
DELETE`/bots/{bot_id}`

Delete a Bot integration.

URI Parameters

HideShow

bot_id: string (required)
ID of the Bot.

BotInstance ¶

A Bot Instance represents an enablement and activation of a Bot Definition for a single organization. When a bot definition is created using the UI, the first bot instance is created and enabled alongside it for the owning organization.

An instance record can be enabled or disabled. Bot instance meta variables specify organization-specific bot settings. The bot definition’s root instance’s meta variables serve as the default configuration that can be customized.

A Bot Instance has the following properties:

Property	Type	Description	Example
id	string	The unique ID of the BotInstance.	5876bc219b9d2b54a0c464ca
organization	string	The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations.	5876bc219b9d2b54a0c464c9
bot	string*	The ID of the bot that is associated to the bot instance	5876bc219b9d2b54a0c464c9
name	string*	Bot name override for the botInstance.	BestBot
description	string	Bot description override for the botInstance.	Best bot ever
avatar	string	Avatar url, default from bot.	https://yoursite.com/avatar.png
enabled	boolean	Enable/disable this bot instance Defaults to true.	true
meta	MetaParams	Free-form object of key-values.	{MetaParams}
createdBy	string	The ID of the user created this bot instance	5876bc219b9d2b54a0c464c9
updatedBy	string	The ID of the user last updated this bot instance	5876bc219b9d2b54a0c464c9
createdAt	string	ISO8601 date and time of when the BotInstance was created.	2020-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of when the BotInstance was last modified.	2020-01-07T14:03:43Z

GET https://api.web1on1.chat/v2/botinstances

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "5876bc219b9d2b54a0c464ca",
    "organization": "5876bc219b9d2b54a0c464c9",
    "bot": "5876bc219b9d2b54a0c464c9",
    "name": "BestBot",
    "description": "Best bot ever",
    "avatar": "https://yoursite.com/avatar.png",
    "enabled": true,
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "createdBy": "5876bc219b9d2b54a0c464c9",
    "updatedBy": "5876bc219b9d2b54a0c464c9",
    "createdAt": "2020-01-07T14:03:43Z",
    "updatedAt": "2020-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All BotInstances
GET`/botinstances`

Return a list of all botInstances.

POST https://api.web1on1.chat/v2/botinstances

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "5876bc219b9d2b54a0c464c9",
  "bot": "5876bc219b9d2b54a0c464c9",
  "name": "BestBot",
  "description": "Best bot ever",
  "avatar": "https://yoursite.com/avatar.png",
  "enabled": true,
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "bot": {
      "type": "string",
      "description": "The ID of the bot that is associated to the bot instance"
    },
    "name": {
      "type": "string",
      "description": "Bot name override for the botInstance."
    },
    "description": {
      "type": "string",
      "description": "Bot description override for the botInstance."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar url, default from bot."
    },
    "enabled": {
      "type": "boolean",
      "description": "Enable/disable this bot instance",
      "default": true
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    }
  },
  "required": [
    "bot",
    "name"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /botinstances/5876bc219b9d2b54a0c464ca

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "bot": "5876bc219b9d2b54a0c464c9",
  "name": "BestBot",
  "description": "Best bot ever",
  "avatar": "https://yoursite.com/avatar.png",
  "enabled": true,
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdBy": "5876bc219b9d2b54a0c464c9",
  "updatedBy": "5876bc219b9d2b54a0c464c9",
  "createdAt": "2020-01-07T14:03:43Z",
  "updatedAt": "2020-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the BotInstance."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "bot": {
      "type": "string",
      "description": "The ID of the bot that is associated to the bot instance"
    },
    "name": {
      "type": "string",
      "description": "Bot name override for the botInstance."
    },
    "description": {
      "type": "string",
      "description": "Bot description override for the botInstance."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar url, default from bot."
    },
    "enabled": {
      "type": "boolean",
      "description": "Enable/disable this bot instance",
      "default": true
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "createdBy": {
      "type": "string",
      "description": "The ID of the user created this bot instance"
    },
    "updatedBy": {
      "type": "string",
      "description": "The ID of the user last updated this bot instance"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the BotInstance was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the BotInstance was last modified."
    }
  },
  "required": [
    "bot",
    "name"
  ]
}

Create a New BotInstance
POST`/botinstances`

You can create a BotInstance using this action.

BotInstance ¶

GET https://api.web1on1.chat/v2/botinstances/botInstance_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "bot": "5876bc219b9d2b54a0c464c9",
  "name": "BestBot",
  "description": "Best bot ever",
  "avatar": "https://yoursite.com/avatar.png",
  "enabled": true,
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdBy": "5876bc219b9d2b54a0c464c9",
  "updatedBy": "5876bc219b9d2b54a0c464c9",
  "createdAt": "2020-01-07T14:03:43Z",
  "updatedAt": "2020-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the BotInstance."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "bot": {
      "type": "string",
      "description": "The ID of the bot that is associated to the bot instance"
    },
    "name": {
      "type": "string",
      "description": "Bot name override for the botInstance."
    },
    "description": {
      "type": "string",
      "description": "Bot description override for the botInstance."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar url, default from bot."
    },
    "enabled": {
      "type": "boolean",
      "description": "Enable/disable this bot instance",
      "default": true
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "createdBy": {
      "type": "string",
      "description": "The ID of the user created this bot instance"
    },
    "updatedBy": {
      "type": "string",
      "description": "The ID of the user last updated this bot instance"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the BotInstance was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the BotInstance was last modified."
    }
  },
  "required": [
    "bot",
    "name"
  ]
}

Retrieve a BotInstance
GET`/botinstances/{botInstance_id}`

Returns a specific BotInstance.

URI Parameters

HideShow

botInstance_id: string (required)
ID of the BotInstance.

PATCH https://api.web1on1.chat/v2/botinstances/botInstance_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "5876bc219b9d2b54a0c464c9",
  "bot": "5876bc219b9d2b54a0c464c9",
  "name": "BestBot",
  "description": "Best bot ever",
  "avatar": "https://yoursite.com/avatar.png",
  "enabled": true,
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "bot": {
      "type": "string",
      "description": "The ID of the bot that is associated to the bot instance"
    },
    "name": {
      "type": "string",
      "description": "Bot name override for the botInstance."
    },
    "description": {
      "type": "string",
      "description": "Bot description override for the botInstance."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar url, default from bot."
    },
    "enabled": {
      "type": "boolean",
      "description": "Enable/disable this bot instance",
      "default": true
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    }
  },
  "required": [
    "bot",
    "name"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "bot": "5876bc219b9d2b54a0c464c9",
  "name": "BestBot",
  "description": "Best bot ever",
  "avatar": "https://yoursite.com/avatar.png",
  "enabled": true,
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdBy": "5876bc219b9d2b54a0c464c9",
  "updatedBy": "5876bc219b9d2b54a0c464c9",
  "createdAt": "2020-01-07T14:03:43Z",
  "updatedAt": "2020-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the BotInstance."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Bot. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "bot": {
      "type": "string",
      "description": "The ID of the bot that is associated to the bot instance"
    },
    "name": {
      "type": "string",
      "description": "Bot name override for the botInstance."
    },
    "description": {
      "type": "string",
      "description": "Bot description override for the botInstance."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar url, default from bot."
    },
    "enabled": {
      "type": "boolean",
      "description": "Enable/disable this bot instance",
      "default": true
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "createdBy": {
      "type": "string",
      "description": "The ID of the user created this bot instance"
    },
    "updatedBy": {
      "type": "string",
      "description": "The ID of the user last updated this bot instance"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the BotInstance was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the BotInstance was last modified."
    }
  },
  "required": [
    "bot",
    "name"
  ]
}

Update a BotInstance
PATCH`/botinstances/{botInstance_id}`

Update a BotInstance using this call.

URI Parameters

HideShow

botInstance_id: string (required)
ID of the BotInstance.

DELETE https://api.web1on1.chat/v2/botinstances/botInstance_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete a BotInstance
DELETE`/botinstances/{botInstance_id}`

Delete a BotInstance

URI Parameters

HideShow

botInstance_id: string (required)
ID of the BotInstance.

Services ¶

A Service can represent any kind of connector, touchpoint, webservice or other integration that allows browsers and remote systems to enter Web1on1’s world.

Examples are XMPP connections, website widgets, remote API calls or other communication channels. Services that are used as notification- or event channels (such as emails or webhooks) may be triggered by events, services that are used as connectors may have connection parameters specified; Web1on1 will do the right thing based on the service type.

Account managers may enable services from the organization Integrations page, where you might find sections for adding XMPP accounts and third-party service providers. Multiple services may be attached/removed to or from a conversation during its lifecycle.

A Service object has the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the Service.	5876bc219b9d2b54a0c464ca
organization	string	The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations.	5876bc219b9d2b54a0c464c9
name	string*	Name of the service.	SmartSupp Widget
description	string	Description of the service.	Test widget at http://domain/test-widget
type	enum	Supported type; service provider. One of smartsupp, intercom, smooch, twilio, mailgun, messenger, api, webhook, gbm. Defaults to webhook.	smartsupp
status	enum	Service status. One of queued, active, disabled, pendingArchive, archived. Defaults to queued.	queued
touchpoints	array	Consumer touchpoints supported by this service integration.	[web]
params	ServiceParams*	Service connection parameters.	{ServiceParams}
smoochId	string	Smooch service ID, if relevant.	58caef23feee32390091168a
smoochAppId	string	Smooch App ID, if relevant.	app_58caef23feee32390091168a
startDate	string	ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`.	2017-01-11T23:13:35.000Z
endDate	string	ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`.	2017-01-11T23:13:35.000Z
meta	MetaParams	Free-form object of key-value pairs.	{MetaParams}
createdAt	string	ISO8601 date and time of when the Service was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of when the Service was last modified.	2016-01-07T14:03:43Z

The content of the params object (connection parameters) depends on the service provider. These are:

Smooch

Required Smooch connection parameter credentials:

appId: 5876bc219b9d2b54a086647fd5 (string, required) - Smooch AppID
keyId: app_5876bc219b9d2b5400d34558 (string) - Smooch application key
secret: 0BPGhSWvROXtb37fkp8Q4iJO (string) - Smooch application secret

Others

In addition, there are two internal service types that can be configured; the webhook type needs an URL as parameter, the api service type may receive a list of scopes.

GET https://api.web1on1.chat/v2/services

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "type": "smooch",
    "params": {
      "mailto": "werkplaats@dealer.nl"
    }
  }
]

List All Services
GET`/services`

Return a list of all services.

POST https://api.web1on1.chat/v2/services

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "SmartSupp Widget",
  "description": "Test widget at http://domain/test-widget",
  "type": "smartsupp",
  "status": "queued",
  "touchpoints": [
    "web",
    "email",
    "sms",
    "facebook",
    "whatsapp"
  ],
  "params": {
    "jid": "uid3710@s1.smartsupp.com",
    "password": "z3kRuD",
    "host": "s1.smartsupp.com",
    "port": "5222",
    "location": "5876bc219b9d2b54a0c464c9",
    "privacy": "https://web1on1.chat/privacy",
    "welcomeMessage": "Welcome",
    "starter": "Hello",
    "startTime": "00:00",
    "endTime": "23:59",
    "startDay": "MONDAY",
    "endDay": "SUNDAY",
    "step": "verifyAgent"
  },
  "smoochId": "58caef23feee32390091168a",
  "smoochAppId": "app_58caef23feee32390091168a",
  "startDate": "2017-01-11T23:13:35.000Z",
  "endDate": "2017-01-11T23:13:35.000Z",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the service."
    },
    "description": {
      "type": "string",
      "description": "Description of the service."
    },
    "type": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "api",
        "webhook",
        "gbm"
      ],
      "default": "webhook",
      "description": "Supported type; service provider."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "disabled",
        "pendingArchive",
        "archived"
      ],
      "default": "queued",
      "description": "Service status."
    },
    "touchpoints": {
      "type": "array",
      "description": "Consumer touchpoints supported by this service integration."
    },
    "params": {
      "type": "object",
      "properties": {
        "jid": {
          "type": "string",
          "description": "JID of the XMPP connection."
        },
        "password": {
          "type": "string",
          "description": "Password for the XMPP connection."
        },
        "host": {
          "type": "string",
          "description": "XMPP host to connect to."
        },
        "port": {
          "type": "string",
          "description": "XMPP port to connect to."
        },
        "location": {
          "type": "string"
        },
        "privacy": {
          "type": "string"
        },
        "welcomeMessage": {
          "type": "string"
        },
        "starter": {
          "type": "string"
        },
        "startTime": {
          "type": "string"
        },
        "endTime": {
          "type": "string"
        },
        "startDay": {
          "type": "string"
        },
        "endDay": {
          "type": "string"
        },
        "step": {
          "type": "string",
          "enum": [
            "verifyAgent",
            "verifyLocation",
            "launchAgent",
            "launchLocation"
          ]
        }
      },
      "required": [
        "jid",
        "password",
        "host",
        "location",
        "welcomeMessage",
        "starter"
      ],
      "description": "Service connection parameters."
    },
    "smoochId": {
      "type": "string",
      "description": "Smooch service ID, if relevant."
    },
    "smoochAppId": {
      "type": "string",
      "description": "Smooch App ID, if relevant."
    },
    "startDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`."
    },
    "endDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs."
    }
  },
  "required": [
    "name",
    "params"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /services/5876bc219b9d2b54a0c464ca

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "SmartSupp Widget",
  "description": "Test widget at http://domain/test-widget",
  "type": "smartsupp",
  "status": "queued",
  "touchpoints": [
    "web",
    "email",
    "sms",
    "facebook",
    "whatsapp"
  ],
  "params": {
    "jid": "uid3710@s1.smartsupp.com",
    "password": "z3kRuD",
    "host": "s1.smartsupp.com",
    "port": "5222",
    "location": "5876bc219b9d2b54a0c464c9",
    "privacy": "https://web1on1.chat/privacy",
    "welcomeMessage": "Welcome",
    "starter": "Hello",
    "startTime": "00:00",
    "endTime": "23:59",
    "startDay": "MONDAY",
    "endDay": "SUNDAY",
    "step": "verifyAgent"
  },
  "smoochId": "58caef23feee32390091168a",
  "smoochAppId": "app_58caef23feee32390091168a",
  "startDate": "2017-01-11T23:13:35.000Z",
  "endDate": "2017-01-11T23:13:35.000Z",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Service."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the service."
    },
    "description": {
      "type": "string",
      "description": "Description of the service."
    },
    "type": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "api",
        "webhook",
        "gbm"
      ],
      "default": "webhook",
      "description": "Supported type; service provider."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "disabled",
        "pendingArchive",
        "archived"
      ],
      "default": "queued",
      "description": "Service status."
    },
    "touchpoints": {
      "type": "array",
      "description": "Consumer touchpoints supported by this service integration."
    },
    "params": {
      "type": "object",
      "properties": {
        "jid": {
          "type": "string",
          "description": "JID of the XMPP connection."
        },
        "password": {
          "type": "string",
          "description": "Password for the XMPP connection."
        },
        "host": {
          "type": "string",
          "description": "XMPP host to connect to."
        },
        "port": {
          "type": "string",
          "description": "XMPP port to connect to."
        },
        "location": {
          "type": "string"
        },
        "privacy": {
          "type": "string"
        },
        "welcomeMessage": {
          "type": "string"
        },
        "starter": {
          "type": "string"
        },
        "startTime": {
          "type": "string"
        },
        "endTime": {
          "type": "string"
        },
        "startDay": {
          "type": "string"
        },
        "endDay": {
          "type": "string"
        },
        "step": {
          "type": "string",
          "enum": [
            "verifyAgent",
            "verifyLocation",
            "launchAgent",
            "launchLocation"
          ]
        }
      },
      "required": [
        "jid",
        "password",
        "host",
        "location",
        "welcomeMessage",
        "starter"
      ],
      "description": "Service connection parameters."
    },
    "smoochId": {
      "type": "string",
      "description": "Smooch service ID, if relevant."
    },
    "smoochAppId": {
      "type": "string",
      "description": "Smooch App ID, if relevant."
    },
    "startDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`."
    },
    "endDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was last modified."
    }
  },
  "required": [
    "name",
    "params"
  ]
}

Create a New Service
POST`/services`

You can create a Service integration using this action.

Service ¶

GET https://api.web1on1.chat/v2/services/service_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "SmartSupp Widget",
  "description": "Test widget at http://domain/test-widget",
  "type": "smartsupp",
  "status": "queued",
  "touchpoints": [
    "web",
    "email",
    "sms",
    "facebook",
    "whatsapp"
  ],
  "params": {
    "jid": "uid3710@s1.smartsupp.com",
    "password": "z3kRuD",
    "host": "s1.smartsupp.com",
    "port": "5222",
    "location": "5876bc219b9d2b54a0c464c9",
    "privacy": "https://web1on1.chat/privacy",
    "welcomeMessage": "Welcome",
    "starter": "Hello",
    "startTime": "00:00",
    "endTime": "23:59",
    "startDay": "MONDAY",
    "endDay": "SUNDAY",
    "step": "verifyAgent"
  },
  "smoochId": "58caef23feee32390091168a",
  "smoochAppId": "app_58caef23feee32390091168a",
  "startDate": "2017-01-11T23:13:35.000Z",
  "endDate": "2017-01-11T23:13:35.000Z",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Service."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the service."
    },
    "description": {
      "type": "string",
      "description": "Description of the service."
    },
    "type": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "api",
        "webhook",
        "gbm"
      ],
      "default": "webhook",
      "description": "Supported type; service provider."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "disabled",
        "pendingArchive",
        "archived"
      ],
      "default": "queued",
      "description": "Service status."
    },
    "touchpoints": {
      "type": "array",
      "description": "Consumer touchpoints supported by this service integration."
    },
    "params": {
      "type": "object",
      "properties": {
        "jid": {
          "type": "string",
          "description": "JID of the XMPP connection."
        },
        "password": {
          "type": "string",
          "description": "Password for the XMPP connection."
        },
        "host": {
          "type": "string",
          "description": "XMPP host to connect to."
        },
        "port": {
          "type": "string",
          "description": "XMPP port to connect to."
        },
        "location": {
          "type": "string"
        },
        "privacy": {
          "type": "string"
        },
        "welcomeMessage": {
          "type": "string"
        },
        "starter": {
          "type": "string"
        },
        "startTime": {
          "type": "string"
        },
        "endTime": {
          "type": "string"
        },
        "startDay": {
          "type": "string"
        },
        "endDay": {
          "type": "string"
        },
        "step": {
          "type": "string",
          "enum": [
            "verifyAgent",
            "verifyLocation",
            "launchAgent",
            "launchLocation"
          ]
        }
      },
      "required": [
        "jid",
        "password",
        "host",
        "location",
        "welcomeMessage",
        "starter"
      ],
      "description": "Service connection parameters."
    },
    "smoochId": {
      "type": "string",
      "description": "Smooch service ID, if relevant."
    },
    "smoochAppId": {
      "type": "string",
      "description": "Smooch App ID, if relevant."
    },
    "startDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`."
    },
    "endDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was last modified."
    }
  },
  "required": [
    "name",
    "params"
  ]
}

Retrieve a Service
GET`/services/{service_id}`

Returns a specific Service integration.

URI Parameters

HideShow

service_id: string (required)
ID of the Service.

PATCH https://api.web1on1.chat/v2/services/service_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "SmartSupp Widget",
  "description": "Test widget at http://domain/test-widget",
  "type": "smartsupp",
  "status": "queued",
  "touchpoints": [
    "web",
    "email",
    "sms",
    "facebook",
    "whatsapp"
  ],
  "params": {
    "jid": "uid3710@s1.smartsupp.com",
    "password": "z3kRuD",
    "host": "s1.smartsupp.com",
    "port": "5222",
    "location": "5876bc219b9d2b54a0c464c9",
    "privacy": "https://web1on1.chat/privacy",
    "welcomeMessage": "Welcome",
    "starter": "Hello",
    "startTime": "00:00",
    "endTime": "23:59",
    "startDay": "MONDAY",
    "endDay": "SUNDAY",
    "step": "verifyAgent"
  },
  "smoochId": "58caef23feee32390091168a",
  "smoochAppId": "app_58caef23feee32390091168a",
  "startDate": "2017-01-11T23:13:35.000Z",
  "endDate": "2017-01-11T23:13:35.000Z",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the service."
    },
    "description": {
      "type": "string",
      "description": "Description of the service."
    },
    "type": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "api",
        "webhook",
        "gbm"
      ],
      "default": "webhook",
      "description": "Supported type; service provider."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "disabled",
        "pendingArchive",
        "archived"
      ],
      "default": "queued",
      "description": "Service status."
    },
    "touchpoints": {
      "type": "array",
      "description": "Consumer touchpoints supported by this service integration."
    },
    "params": {
      "type": "object",
      "properties": {
        "jid": {
          "type": "string",
          "description": "JID of the XMPP connection."
        },
        "password": {
          "type": "string",
          "description": "Password for the XMPP connection."
        },
        "host": {
          "type": "string",
          "description": "XMPP host to connect to."
        },
        "port": {
          "type": "string",
          "description": "XMPP port to connect to."
        },
        "location": {
          "type": "string"
        },
        "privacy": {
          "type": "string"
        },
        "welcomeMessage": {
          "type": "string"
        },
        "starter": {
          "type": "string"
        },
        "startTime": {
          "type": "string"
        },
        "endTime": {
          "type": "string"
        },
        "startDay": {
          "type": "string"
        },
        "endDay": {
          "type": "string"
        },
        "step": {
          "type": "string",
          "enum": [
            "verifyAgent",
            "verifyLocation",
            "launchAgent",
            "launchLocation"
          ]
        }
      },
      "required": [
        "jid",
        "password",
        "host",
        "location",
        "welcomeMessage",
        "starter"
      ],
      "description": "Service connection parameters."
    },
    "smoochId": {
      "type": "string",
      "description": "Smooch service ID, if relevant."
    },
    "smoochAppId": {
      "type": "string",
      "description": "Smooch App ID, if relevant."
    },
    "startDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`."
    },
    "endDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs."
    }
  },
  "required": [
    "name",
    "params"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "SmartSupp Widget",
  "description": "Test widget at http://domain/test-widget",
  "type": "smartsupp",
  "status": "queued",
  "touchpoints": [
    "web",
    "email",
    "sms",
    "facebook",
    "whatsapp"
  ],
  "params": {
    "jid": "uid3710@s1.smartsupp.com",
    "password": "z3kRuD",
    "host": "s1.smartsupp.com",
    "port": "5222",
    "location": "5876bc219b9d2b54a0c464c9",
    "privacy": "https://web1on1.chat/privacy",
    "welcomeMessage": "Welcome",
    "starter": "Hello",
    "startTime": "00:00",
    "endTime": "23:59",
    "startDay": "MONDAY",
    "endDay": "SUNDAY",
    "step": "verifyAgent"
  },
  "smoochId": "58caef23feee32390091168a",
  "smoochAppId": "app_58caef23feee32390091168a",
  "startDate": "2017-01-11T23:13:35.000Z",
  "endDate": "2017-01-11T23:13:35.000Z",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Service."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the service."
    },
    "description": {
      "type": "string",
      "description": "Description of the service."
    },
    "type": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "api",
        "webhook",
        "gbm"
      ],
      "default": "webhook",
      "description": "Supported type; service provider."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "disabled",
        "pendingArchive",
        "archived"
      ],
      "default": "queued",
      "description": "Service status."
    },
    "touchpoints": {
      "type": "array",
      "description": "Consumer touchpoints supported by this service integration."
    },
    "params": {
      "type": "object",
      "properties": {
        "jid": {
          "type": "string",
          "description": "JID of the XMPP connection."
        },
        "password": {
          "type": "string",
          "description": "Password for the XMPP connection."
        },
        "host": {
          "type": "string",
          "description": "XMPP host to connect to."
        },
        "port": {
          "type": "string",
          "description": "XMPP port to connect to."
        },
        "location": {
          "type": "string"
        },
        "privacy": {
          "type": "string"
        },
        "welcomeMessage": {
          "type": "string"
        },
        "starter": {
          "type": "string"
        },
        "startTime": {
          "type": "string"
        },
        "endTime": {
          "type": "string"
        },
        "startDay": {
          "type": "string"
        },
        "endDay": {
          "type": "string"
        },
        "step": {
          "type": "string",
          "enum": [
            "verifyAgent",
            "verifyLocation",
            "launchAgent",
            "launchLocation"
          ]
        }
      },
      "required": [
        "jid",
        "password",
        "host",
        "location",
        "welcomeMessage",
        "starter"
      ],
      "description": "Service connection parameters."
    },
    "smoochId": {
      "type": "string",
      "description": "Smooch service ID, if relevant."
    },
    "smoochAppId": {
      "type": "string",
      "description": "Smooch App ID, if relevant."
    },
    "startDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`."
    },
    "endDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was last modified."
    }
  },
  "required": [
    "name",
    "params"
  ]
}

Update a Service
PATCH`/services/{service_id}`

Update a Service integration using this call.

URI Parameters

HideShow

service_id: string (required)
ID of the Service.

DELETE https://api.web1on1.chat/v2/services/service_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete a Service
DELETE`/services/{service_id}`

Delete a Service integration.

URI Parameters

HideShow

service_id: string (required)
ID of the Service.

Forms ¶

The Forms API provides methods to manage collections of fields.

A Form has the following properties:

Property	Type	Description	Example
id	string	Unique identifier for the form	5656f3ca42fc302027eba5c6
organization	string	Organization ID of the owning organization. Defaults to the API user’s active organization.	58bcbafb8547f04f68c14bdb
name	string*	Name of the form	Brochure
type	enum	Form type. A `static` form always stays active, while a `topic` is picked by the agent. One of topic, static. Defaults to topic.	topic
template	string	Form ID of the form that was used as a template.	5c7574c78ae07962b12e264c
profileFields	array	List of profile fields for this form	[gender]
fields	array	List of fields for this form	[{FormField Create}]
notifyEmails	array	A list of email addresses where form results get sent to.	[support@example.com]
status	enum	State of the form. Archived forms are not made available in the UI. One of active, archived. Defaults to active.	active
tags	array	List of sharing tags for the form. The form will be made available to child organizations with matching tags.	[automotive]
labels	array	List of labels for the form. Form labels will be passed on in conversation.forms, as well as conversation.results and in Results messages when the form is processed.	[isLead]
pointsByAgent	number	Number of points when an agent submits a result with this form.	60
pointsByBot	number	Number of points when a bot submits a result with this form.	40
meta	MetaParams	Free-form object of key-values, that will be passed on to external systems.	{MetaParams}
createdAt	string	ISO8601 date and time of when the form was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of when the form was last modified.	2016-01-07T14:03:43Z

The profileFields attribute specifies which contact profile fields are included in form results. The list of profileFields can be one or more of honorificPrefix, initials, honorificSuffix, gender, givenName, familyName, additionalName, streetAddress, streetNumber, postalCode, addressLocality, addressRegion, addressCountry, worksFor, email or telephone.

In addition to profile fields, a form may have one or more form-specific fields. Each field has the following properties:

Property	Type	Description	Example
id	string	Unique identifier for the field.	5877ff19276f4e04db18e330
name	string*	Field identifier, short name to identify the field	appointmentDate
label	string	HTML label to add to the field	Appointment Date
type	enum	HTML5 input type, and the elements ‘select’ and ‘textearea’. One of button, checkbox, color, date, datetime-local, email, file, hidden, image, month, number, password, radio, range, reset, search, select, submit, tel, text, textarea, time, url, week. Defaults to text.	button
entity	string	Name of the entity that this field represents.	Date
pattern	string	HTML5 input pattern attribute, a JavaScript regular expression which the input’s value must match.	(?:19
options	array	An array of options for select form field to display. Each option should be an object with a ‘key’ (string) and a ‘value’ (string).	[{FormFieldOption}]
required	boolean	Field is required. Defaults to false.	false
createdAt	string	ISO8601 date and time of when the form field was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of when the form field was last modified.	2016-01-07T14:03:43Z

GET https://api.web1on1.chat/v2/forms

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "5656f3ca42fc302027eba5c6",
    "organization": "58bcbafb8547f04f68c14bdb",
    "name": "Brochure",
    "type": "topic",
    "template": "5c7574c78ae07962b12e264c",
    "profileFields": [
      "gender",
      "honorificPrefix",
      "honorificSuffix",
      "initials",
      "givenName",
      "familyName",
      "additionalName",
      "streetAddress",
      "streetNumber",
      "postalCode",
      "addressLocality",
      "addressRegion",
      "addressCountry",
      "worksFor",
      "email",
      "telephone"
    ],
    "fields": [
      {
        "name": "appointmentDate",
        "label": "Appointment Date",
        "type": "button",
        "entity": "Date",
        "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
        "options": [
          {
            "key": "yes",
            "value": "Y"
          }
        ],
        "required": true
      }
    ],
    "notifyEmails": [
      "support@example.com",
      "help@example.com"
    ],
    "status": "active",
    "tags": [
      "automotive",
      "insurance"
    ],
    "labels": [
      "isLead",
      "isBrand"
    ],
    "pointsByAgent": 60,
    "pointsByBot": 40,
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Forms
GET`/forms`

Return a list of all forms for the organization and sub-organizations.

POST https://api.web1on1.chat/v2/forms

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Brochure",
  "type": "topic",
  "template": "5c7574c78ae07962b12e264c",
  "profileFields": [
    "gender",
    "honorificPrefix",
    "honorificSuffix",
    "initials",
    "givenName",
    "familyName",
    "additionalName",
    "streetAddress",
    "streetNumber",
    "postalCode",
    "addressLocality",
    "addressRegion",
    "addressCountry",
    "worksFor",
    "email",
    "telephone"
  ],
  "fields": [
    {
      "name": "appointmentDate",
      "label": "Appointment Date",
      "type": "button",
      "entity": "Date",
      "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
      "options": [
        {
          "key": "yes",
          "value": "Y"
        }
      ],
      "required": true
    }
  ],
  "notifyEmails": [
    "support@example.com",
    "help@example.com"
  ],
  "status": "active",
  "tags": [
    "automotive",
    "insurance"
  ],
  "labels": [
    "isLead",
    "isBrand"
  ],
  "pointsByAgent": 60,
  "pointsByBot": 40,
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization. Defaults to the API user's active organization."
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "type": {
      "type": "string",
      "enum": [
        "topic",
        "static"
      ],
      "default": "topic",
      "description": "Form type. A `static` form always stays active, while a `topic` is picked by the agent."
    },
    "template": {
      "type": "string",
      "description": "Form ID of the form that was used as a template."
    },
    "profileFields": {
      "type": "array",
      "description": "List of profile fields for this form"
    },
    "fields": {
      "type": "array",
      "description": "List of fields for this form"
    },
    "notifyEmails": {
      "type": "array",
      "description": "A list of email addresses where form results get sent to."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ],
      "default": "active",
      "description": "State of the form. Archived forms are not made available in the UI."
    },
    "tags": {
      "type": "array",
      "description": "List of sharing tags for the form. The form will be made available to child organizations with matching tags."
    },
    "labels": {
      "type": "array",
      "description": "List of labels for the form. Form labels will be passed on in conversation.forms, as well as conversation.results and in Results messages when the form is processed."
    },
    "pointsByAgent": {
      "type": "number",
      "description": "Number of points when an agent submits a result with this form."
    },
    "pointsByBot": {
      "type": "number",
      "description": "Number of points when a bot submits a result with this form."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems."
    }
  },
  "required": [
    "name"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /forms/5656f3ca42fc302027eba5c6

Body

{
  "id": "5656f3ca42fc302027eba5c6",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Brochure",
  "type": "topic",
  "template": "5c7574c78ae07962b12e264c",
  "profileFields": [
    "gender",
    "honorificPrefix",
    "honorificSuffix",
    "initials",
    "givenName",
    "familyName",
    "additionalName",
    "streetAddress",
    "streetNumber",
    "postalCode",
    "addressLocality",
    "addressRegion",
    "addressCountry",
    "worksFor",
    "email",
    "telephone"
  ],
  "fields": [
    {
      "name": "appointmentDate",
      "label": "Appointment Date",
      "type": "button",
      "entity": "Date",
      "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
      "options": [
        {
          "key": "yes",
          "value": "Y"
        }
      ],
      "required": true
    }
  ],
  "notifyEmails": [
    "support@example.com",
    "help@example.com"
  ],
  "status": "active",
  "tags": [
    "automotive",
    "insurance"
  ],
  "labels": [
    "isLead",
    "isBrand"
  ],
  "pointsByAgent": 60,
  "pointsByBot": 40,
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the form"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization. Defaults to the API user's active organization."
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "type": {
      "type": "string",
      "enum": [
        "topic",
        "static"
      ],
      "default": "topic",
      "description": "Form type. A `static` form always stays active, while a `topic` is picked by the agent."
    },
    "template": {
      "type": "string",
      "description": "Form ID of the form that was used as a template."
    },
    "profileFields": {
      "type": "array",
      "description": "List of profile fields for this form"
    },
    "fields": {
      "type": "array",
      "description": "List of fields for this form"
    },
    "notifyEmails": {
      "type": "array",
      "description": "A list of email addresses where form results get sent to."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ],
      "default": "active",
      "description": "State of the form. Archived forms are not made available in the UI."
    },
    "tags": {
      "type": "array",
      "description": "List of sharing tags for the form. The form will be made available to child organizations with matching tags."
    },
    "labels": {
      "type": "array",
      "description": "List of labels for the form. Form labels will be passed on in conversation.forms, as well as conversation.results and in Results messages when the form is processed."
    },
    "pointsByAgent": {
      "type": "number",
      "description": "Number of points when an agent submits a result with this form."
    },
    "pointsByBot": {
      "type": "number",
      "description": "Number of points when a bot submits a result with this form."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Create a new Form
POST`/forms`

You may create a form using this action.

Form ¶

GET https://api.web1on1.chat/v2/forms/form_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5656f3ca42fc302027eba5c6",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Brochure",
  "type": "topic",
  "template": "5c7574c78ae07962b12e264c",
  "profileFields": [
    "gender",
    "honorificPrefix",
    "honorificSuffix",
    "initials",
    "givenName",
    "familyName",
    "additionalName",
    "streetAddress",
    "streetNumber",
    "postalCode",
    "addressLocality",
    "addressRegion",
    "addressCountry",
    "worksFor",
    "email",
    "telephone"
  ],
  "fields": [
    {
      "name": "appointmentDate",
      "label": "Appointment Date",
      "type": "button",
      "entity": "Date",
      "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
      "options": [
        {
          "key": "yes",
          "value": "Y"
        }
      ],
      "required": true
    }
  ],
  "notifyEmails": [
    "support@example.com",
    "help@example.com"
  ],
  "status": "active",
  "tags": [
    "automotive",
    "insurance"
  ],
  "labels": [
    "isLead",
    "isBrand"
  ],
  "pointsByAgent": 60,
  "pointsByBot": 40,
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the form"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization. Defaults to the API user's active organization."
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "type": {
      "type": "string",
      "enum": [
        "topic",
        "static"
      ],
      "default": "topic",
      "description": "Form type. A `static` form always stays active, while a `topic` is picked by the agent."
    },
    "template": {
      "type": "string",
      "description": "Form ID of the form that was used as a template."
    },
    "profileFields": {
      "type": "array",
      "description": "List of profile fields for this form"
    },
    "fields": {
      "type": "array",
      "description": "List of fields for this form"
    },
    "notifyEmails": {
      "type": "array",
      "description": "A list of email addresses where form results get sent to."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ],
      "default": "active",
      "description": "State of the form. Archived forms are not made available in the UI."
    },
    "tags": {
      "type": "array",
      "description": "List of sharing tags for the form. The form will be made available to child organizations with matching tags."
    },
    "labels": {
      "type": "array",
      "description": "List of labels for the form. Form labels will be passed on in conversation.forms, as well as conversation.results and in Results messages when the form is processed."
    },
    "pointsByAgent": {
      "type": "number",
      "description": "Number of points when an agent submits a result with this form."
    },
    "pointsByBot": {
      "type": "number",
      "description": "Number of points when a bot submits a result with this form."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Retrieve a Form
GET`/forms/{form_id}`

Returns a specific Form.

URI Parameters

HideShow

form_id: string (required)
ID of the Form.

PATCH https://api.web1on1.chat/v2/forms/form_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Brochure",
  "type": "topic",
  "template": "5c7574c78ae07962b12e264c",
  "profileFields": [
    "gender",
    "honorificPrefix",
    "honorificSuffix",
    "initials",
    "givenName",
    "familyName",
    "additionalName",
    "streetAddress",
    "streetNumber",
    "postalCode",
    "addressLocality",
    "addressRegion",
    "addressCountry",
    "worksFor",
    "email",
    "telephone"
  ],
  "fields": [
    {
      "name": "appointmentDate",
      "label": "Appointment Date",
      "type": "button",
      "entity": "Date",
      "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
      "options": [
        {
          "key": "yes",
          "value": "Y"
        }
      ],
      "required": true
    }
  ],
  "notifyEmails": [
    "support@example.com",
    "help@example.com"
  ],
  "status": "active",
  "tags": [
    "automotive",
    "insurance"
  ],
  "labels": [
    "isLead",
    "isBrand"
  ],
  "pointsByAgent": 60,
  "pointsByBot": 40,
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization. Defaults to the API user's active organization."
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "type": {
      "type": "string",
      "enum": [
        "topic",
        "static"
      ],
      "default": "topic",
      "description": "Form type. A `static` form always stays active, while a `topic` is picked by the agent."
    },
    "template": {
      "type": "string",
      "description": "Form ID of the form that was used as a template."
    },
    "profileFields": {
      "type": "array",
      "description": "List of profile fields for this form"
    },
    "fields": {
      "type": "array",
      "description": "List of fields for this form"
    },
    "notifyEmails": {
      "type": "array",
      "description": "A list of email addresses where form results get sent to."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ],
      "default": "active",
      "description": "State of the form. Archived forms are not made available in the UI."
    },
    "tags": {
      "type": "array",
      "description": "List of sharing tags for the form. The form will be made available to child organizations with matching tags."
    },
    "labels": {
      "type": "array",
      "description": "List of labels for the form. Form labels will be passed on in conversation.forms, as well as conversation.results and in Results messages when the form is processed."
    },
    "pointsByAgent": {
      "type": "number",
      "description": "Number of points when an agent submits a result with this form."
    },
    "pointsByBot": {
      "type": "number",
      "description": "Number of points when a bot submits a result with this form."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems."
    }
  },
  "required": [
    "name"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5656f3ca42fc302027eba5c6",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Brochure",
  "type": "topic",
  "template": "5c7574c78ae07962b12e264c",
  "profileFields": [
    "gender",
    "honorificPrefix",
    "honorificSuffix",
    "initials",
    "givenName",
    "familyName",
    "additionalName",
    "streetAddress",
    "streetNumber",
    "postalCode",
    "addressLocality",
    "addressRegion",
    "addressCountry",
    "worksFor",
    "email",
    "telephone"
  ],
  "fields": [
    {
      "name": "appointmentDate",
      "label": "Appointment Date",
      "type": "button",
      "entity": "Date",
      "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
      "options": [
        {
          "key": "yes",
          "value": "Y"
        }
      ],
      "required": true
    }
  ],
  "notifyEmails": [
    "support@example.com",
    "help@example.com"
  ],
  "status": "active",
  "tags": [
    "automotive",
    "insurance"
  ],
  "labels": [
    "isLead",
    "isBrand"
  ],
  "pointsByAgent": 60,
  "pointsByBot": 40,
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the form"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization. Defaults to the API user's active organization."
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "type": {
      "type": "string",
      "enum": [
        "topic",
        "static"
      ],
      "default": "topic",
      "description": "Form type. A `static` form always stays active, while a `topic` is picked by the agent."
    },
    "template": {
      "type": "string",
      "description": "Form ID of the form that was used as a template."
    },
    "profileFields": {
      "type": "array",
      "description": "List of profile fields for this form"
    },
    "fields": {
      "type": "array",
      "description": "List of fields for this form"
    },
    "notifyEmails": {
      "type": "array",
      "description": "A list of email addresses where form results get sent to."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ],
      "default": "active",
      "description": "State of the form. Archived forms are not made available in the UI."
    },
    "tags": {
      "type": "array",
      "description": "List of sharing tags for the form. The form will be made available to child organizations with matching tags."
    },
    "labels": {
      "type": "array",
      "description": "List of labels for the form. Form labels will be passed on in conversation.forms, as well as conversation.results and in Results messages when the form is processed."
    },
    "pointsByAgent": {
      "type": "number",
      "description": "Number of points when an agent submits a result with this form."
    },
    "pointsByBot": {
      "type": "number",
      "description": "Number of points when a bot submits a result with this form."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update a Form
PATCH`/forms/{form_id}`

Update a specific Form.

URI Parameters

HideShow

form_id: string (required)
ID of the Form.

DELETE https://api.web1on1.chat/v2/forms/form_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete a Form
DELETE`/forms/{form_id}`

Delete a Form, including all its sub-resources.

URI Parameters

HideShow

form_id: string (required)
ID of the Form.

Form Fields ¶

GET https://api.web1on1.chat/v2/forms/form_id/fields

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "5877ff19276f4e04db18e330",
    "name": "appointmentDate",
    "label": "Appointment Date",
    "type": "button",
    "entity": "Date",
    "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
    "options": [
      {
        "key": "yes",
        "value": "Y"
      }
    ],
    "required": true,
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List all Form Fields for a Form
GET`/forms/{form_id}/fields`

Return a list of all form fields for a Form.

URI Parameters

HideShow

form_id: string (required)
ID of the Form.

POST https://api.web1on1.chat/v2/forms/form_id/fields

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "name": "appointmentDate",
  "label": "Appointment Date",
  "type": "button",
  "entity": "Date",
  "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
  "options": [
    {
      "key": "yes",
      "value": "Y"
    }
  ],
  "required": true
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Field identifier, short name to identify the field"
    },
    "label": {
      "type": "string",
      "description": "HTML label to add to the field"
    },
    "type": {
      "type": "string",
      "enum": [
        "button",
        "checkbox",
        "color",
        "date",
        "datetime-local",
        "email",
        "file",
        "hidden",
        "image",
        "month",
        "number",
        "password",
        "radio",
        "range",
        "reset",
        "search",
        "select",
        "submit",
        "tel",
        "text",
        "textarea",
        "time",
        "url",
        "week"
      ],
      "default": "text",
      "description": "HTML5 input type, and the elements 'select' and 'textearea'."
    },
    "entity": {
      "type": "string",
      "description": "Name of the entity that this field represents."
    },
    "pattern": {
      "type": "string",
      "description": "HTML5 input pattern attribute, a JavaScript regular expression which the input's value must match."
    },
    "options": {
      "type": "array",
      "description": "An array of options for select form field to display. Each option should be an object with a 'key' (string) and a 'value' (string)."
    },
    "required": {
      "type": "boolean",
      "description": "Field is required.",
      "default": false
    }
  },
  "required": [
    "name"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /forms/5656f3ca42fc302027eba5c6/fields/5877a5ecb6b1bc76263e0a85

Body

{
  "id": "5877ff19276f4e04db18e330",
  "name": "appointmentDate",
  "label": "Appointment Date",
  "type": "button",
  "entity": "Date",
  "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
  "options": [
    {
      "key": "yes",
      "value": "Y"
    }
  ],
  "required": true,
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the field."
    },
    "name": {
      "type": "string",
      "description": "Field identifier, short name to identify the field"
    },
    "label": {
      "type": "string",
      "description": "HTML label to add to the field"
    },
    "type": {
      "type": "string",
      "enum": [
        "button",
        "checkbox",
        "color",
        "date",
        "datetime-local",
        "email",
        "file",
        "hidden",
        "image",
        "month",
        "number",
        "password",
        "radio",
        "range",
        "reset",
        "search",
        "select",
        "submit",
        "tel",
        "text",
        "textarea",
        "time",
        "url",
        "week"
      ],
      "default": "text",
      "description": "HTML5 input type, and the elements 'select' and 'textearea'."
    },
    "entity": {
      "type": "string",
      "description": "Name of the entity that this field represents."
    },
    "pattern": {
      "type": "string",
      "description": "HTML5 input pattern attribute, a JavaScript regular expression which the input's value must match."
    },
    "options": {
      "type": "array",
      "description": "An array of options for select form field to display. Each option should be an object with a 'key' (string) and a 'value' (string)."
    },
    "required": {
      "type": "boolean",
      "description": "Field is required.",
      "default": false
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Create a new Form Field
POST`/forms/{form_id}/fields`

You may add a form field to a form using this action.

URI Parameters

HideShow

form_id: string (required)
ID of the Form.

GET https://api.web1on1.chat/v2/forms/form_id/fields/field_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5877ff19276f4e04db18e330",
  "name": "appointmentDate",
  "label": "Appointment Date",
  "type": "button",
  "entity": "Date",
  "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
  "options": [
    {
      "key": "yes",
      "value": "Y"
    }
  ],
  "required": true,
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the field."
    },
    "name": {
      "type": "string",
      "description": "Field identifier, short name to identify the field"
    },
    "label": {
      "type": "string",
      "description": "HTML label to add to the field"
    },
    "type": {
      "type": "string",
      "enum": [
        "button",
        "checkbox",
        "color",
        "date",
        "datetime-local",
        "email",
        "file",
        "hidden",
        "image",
        "month",
        "number",
        "password",
        "radio",
        "range",
        "reset",
        "search",
        "select",
        "submit",
        "tel",
        "text",
        "textarea",
        "time",
        "url",
        "week"
      ],
      "default": "text",
      "description": "HTML5 input type, and the elements 'select' and 'textearea'."
    },
    "entity": {
      "type": "string",
      "description": "Name of the entity that this field represents."
    },
    "pattern": {
      "type": "string",
      "description": "HTML5 input pattern attribute, a JavaScript regular expression which the input's value must match."
    },
    "options": {
      "type": "array",
      "description": "An array of options for select form field to display. Each option should be an object with a 'key' (string) and a 'value' (string)."
    },
    "required": {
      "type": "boolean",
      "description": "Field is required.",
      "default": false
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Retrieve a Form Field
GET`/forms/{form_id}/fields/{field_id}`

Returns a specific Form Field for a Form.

URI Parameters

HideShow

form_id: string (required)
ID of the Form.
field_id: string (required)
ID of the Form Field.

PATCH https://api.web1on1.chat/v2/forms/form_id/fields/field_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "name": "appointmentDate",
  "label": "Appointment Date",
  "type": "button",
  "entity": "Date",
  "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
  "options": [
    {
      "key": "yes",
      "value": "Y"
    }
  ],
  "required": true
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Field identifier, short name to identify the field"
    },
    "label": {
      "type": "string",
      "description": "HTML label to add to the field"
    },
    "type": {
      "type": "string",
      "enum": [
        "button",
        "checkbox",
        "color",
        "date",
        "datetime-local",
        "email",
        "file",
        "hidden",
        "image",
        "month",
        "number",
        "password",
        "radio",
        "range",
        "reset",
        "search",
        "select",
        "submit",
        "tel",
        "text",
        "textarea",
        "time",
        "url",
        "week"
      ],
      "default": "text",
      "description": "HTML5 input type, and the elements 'select' and 'textearea'."
    },
    "entity": {
      "type": "string",
      "description": "Name of the entity that this field represents."
    },
    "pattern": {
      "type": "string",
      "description": "HTML5 input pattern attribute, a JavaScript regular expression which the input's value must match."
    },
    "options": {
      "type": "array",
      "description": "An array of options for select form field to display. Each option should be an object with a 'key' (string) and a 'value' (string)."
    },
    "required": {
      "type": "boolean",
      "description": "Field is required.",
      "default": false
    }
  },
  "required": [
    "name"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5877ff19276f4e04db18e330",
  "name": "appointmentDate",
  "label": "Appointment Date",
  "type": "button",
  "entity": "Date",
  "pattern": "(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))",
  "options": [
    {
      "key": "yes",
      "value": "Y"
    }
  ],
  "required": true,
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the field."
    },
    "name": {
      "type": "string",
      "description": "Field identifier, short name to identify the field"
    },
    "label": {
      "type": "string",
      "description": "HTML label to add to the field"
    },
    "type": {
      "type": "string",
      "enum": [
        "button",
        "checkbox",
        "color",
        "date",
        "datetime-local",
        "email",
        "file",
        "hidden",
        "image",
        "month",
        "number",
        "password",
        "radio",
        "range",
        "reset",
        "search",
        "select",
        "submit",
        "tel",
        "text",
        "textarea",
        "time",
        "url",
        "week"
      ],
      "default": "text",
      "description": "HTML5 input type, and the elements 'select' and 'textearea'."
    },
    "entity": {
      "type": "string",
      "description": "Name of the entity that this field represents."
    },
    "pattern": {
      "type": "string",
      "description": "HTML5 input pattern attribute, a JavaScript regular expression which the input's value must match."
    },
    "options": {
      "type": "array",
      "description": "An array of options for select form field to display. Each option should be an object with a 'key' (string) and a 'value' (string)."
    },
    "required": {
      "type": "boolean",
      "description": "Field is required.",
      "default": false
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update a Form Field
PATCH`/forms/{form_id}/fields/{field_id}`

Update a specific Form Field for a Form.

URI Parameters

HideShow

form_id: string (required)
ID of the Form.
field_id: string (required)
ID of the Form Field.

DELETE https://api.web1on1.chat/v2/forms/form_id/fields/field_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete a Form Field
DELETE`/forms/{form_id}/fields/{field_id}`

Delete a Form Field from a Form.

URI Parameters

HideShow

form_id: string (required)
ID of the Form.
field_id: string (required)
ID of the Form Field.

Channels ¶

Users may be assigned to Queue Notification Channels. This allows an agent to subscribe to those channels to receive notifications of new chat requests (the “queue”). When an agent unsubscribes from a channel, he/she will stop receiving channel notifications.

A Channel has the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the Channel.	5877a5ecb6b1bc76263e0a85
name	string*	The name of the Channel.	BC One
organization	string	The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations.	55dcf8aa048ee2227d4aa1a4
members	array	A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean).	[{ChannelMember}]
createdAt	string	ISO8601 date and time when the Channel was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time when the Channel was last modified.	2016-01-07T14:03:43Z

GET https://api.web1on1.chat/v2/channels

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "5877a5ecb6b1bc76263e0a85",
    "name": "BC One",
    "organization": "55dcf8aa048ee2227d4aa1a4",
    "members": [
      {
        "user": "56467a06d9b082b0059151dc",
        "online": false,
        "bucket": "all"
      }
    ],
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Channels
GET`/channels`

Return a list of all Channels.

POST https://api.web1on1.chat/v2/channels

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "name": "BC One",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    {
      "user": "56467a06d9b082b0059151dc",
      "online": false,
      "bucket": "all"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Channel."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
    }
  },
  "required": [
    "name"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /channels/5877a5ecb6b1bc76263e0a85

Body

{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "BC One",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    {
      "user": "56467a06d9b082b0059151dc",
      "online": false,
      "bucket": "all"
    }
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Channel."
    },
    "name": {
      "type": "string",
      "description": "The name of the Channel."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Create a New Channel
POST`/channels`

You may create a Channel using this action.

Channel ¶

GET https://api.web1on1.chat/v2/channels/channel_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "BC One",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    {
      "user": "56467a06d9b082b0059151dc",
      "online": false,
      "bucket": "all"
    }
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Channel."
    },
    "name": {
      "type": "string",
      "description": "The name of the Channel."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Retrieve a Channel
GET`/channels/{channel_id}`

Returns a specific Channel.

URI Parameters

HideShow

channel_id: string (required)
ID of the Channel.

PATCH https://api.web1on1.chat/v2/channels/channel_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "name": "BC One",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    {
      "user": "56467a06d9b082b0059151dc",
      "online": false,
      "bucket": "all"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Channel."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
    }
  },
  "required": [
    "name"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "BC One",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    {
      "user": "56467a06d9b082b0059151dc",
      "online": false,
      "bucket": "all"
    }
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Channel."
    },
    "name": {
      "type": "string",
      "description": "The name of the Channel."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update a Channel
PATCH`/channels/{channel_id}`

Update a specific Channel.

URI Parameters

HideShow

channel_id: string (required)
ID of the Channel.

DELETE https://api.web1on1.chat/v2/channels/channel_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses204

This response has no content.

Delete a Channel
DELETE`/channels/{channel_id}`

Delete a Channel.

URI Parameters

HideShow

channel_id: string (required)
ID of the Channel.

GET https://api.web1on1.chat/v2/channels/channel_id/members

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "user": "56467a06d9b082b0059151dc",
    "online": false,
    "bucket": "all"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Retrieve all Channel members
GET`/channels/{channel_id}/members`

Returns all Users - as channel member objects - that are a member of a specific Channel.

URI Parameters

HideShow

channel_id: string (required)
ID of the Channel.

POST https://api.web1on1.chat/v2/channels/channel_id/members

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "user": "56467a06d9b082b0059151dc",
  "online": false,
  "bucket": "all"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "user": {
      "type": "string",
      "description": "The ID of the User that may subscribe to the channel."
    },
    "online": {
      "type": "boolean",
      "description": "Flag signifying if the user is currently subscribed to the channel.",
      "default": false
    },
    "bucket": {
      "type": "string",
      "description": "Setup a bucket for this channel, defaults to all",
      "default": "all"
    }
  },
  "required": [
    "user",
    "bucket"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /channels/5877a5ecb6b1bc76263e0a85

Body

{
  "user": "56467a06d9b082b0059151dc",
  "online": false,
  "bucket": "all"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "user": {
      "type": "string",
      "description": "The ID of the User that may subscribe to the channel."
    },
    "online": {
      "type": "boolean",
      "description": "Flag signifying if the user is currently subscribed to the channel.",
      "default": false
    },
    "bucket": {
      "type": "string",
      "description": "Setup a bucket for this channel, defaults to all",
      "default": "all"
    }
  },
  "required": [
    "user",
    "bucket"
  ]
}

Add agents to a channel
POST`/channels/{channel_id}/members`

You may add one or more agent members to a Channel using this action.

URI Parameters

HideShow

channel_id: string (required)
ID of the Channel.

DELETE https://api.web1on1.chat/v2/channels/channel_id/members/user_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Remove an agent from a channel
DELETE`/channels/{channel_id}/members/{user_id}`

Remove a User from a Channel.

URI Parameters

HideShow

channel_id: string (required)
ID of the Channel.
user_id: string (required)
ID of the User.

Workflows ¶

Workflows store and execute rules, emit events, and maintain the state needed to route queued conversations to user notification channels. Workflows are executed using a powerful, lightweight rules engine.

Each workflow may be limited to a selected set of organizations and/or, more dynamically, a set of organization tags.

Whenever a conversation enters the state queued, all workflows of the owning organization are run. In addition, all workflows of any parent organizations are run that are not limited to exclude the conversations’s organization (by specifying applicable organizations and organization tags for the workflow).

A Workflow has the following attributes:

Property	Type	Description	Example
id	string	The unique ID of the Workflow.	56467a06d9b082b0059151dc
organization	string	Organization ID, conversation owner. Defaults to the API key owner.	58bcbafb8547f04f68c14bdb
name	string*	Name of the Workflow.	Automotive - Generic
enabled	boolean	Boolean to switch the workflow on or off. Defaults to true.	true
rules	array	An array of rules that are matched to facts.	[{WfRule}]
organizations	array	List of Organization IDs to limit the workflow to.	[58bc9aecd906223dcec36495]
organizationTags	array	List of OrganizationGroup IDs to limit the workflow to.	[56467a06d9b082b0059151dc]
createdAt	string	ISO8601 date and time when the Workflow was created.	2017-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time when the Workflow was last modified.	2017-01-07T14:03:43Z

For further information on structuring workflows, please review the Provisioning Guide.

GET https://api.web1on1.chat/v2/workflows

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "56467a06d9b082b0059151dc",
    "organization": "58bcbafb8547f04f68c14bdb",
    "name": "Automotive - Generic",
    "enabled": true,
    "rules": [
      {
        "id": "58bc9aecd906223dcec36493",
        "conditions": {
          "any": [
            {
              "fact": "conversation.category",
              "operator": "match",
              "value": "Used Car",
              "path": ".meta"
            }
          ],
          "all": [
            {
              "fact": "conversation.category",
              "operator": "match",
              "value": "Used Car",
              "path": ".meta"
            }
          ]
        },
        "event": {
          "type": "enqueue",
          "params": {
            "name": "Sales",
            "channel": "58bc9aecd906223dcec36493",
            "delay": 20
          }
        },
        "priority": 1
      }
    ],
    "organizations": [
      "58bc9aecd906223dcec36495",
      "58bc9aecd906223dcec36493"
    ],
    "organizationTags": [
      "56467a06d9b082b0059151dc"
    ],
    "createdAt": "2017-01-07T14:03:43Z",
    "updatedAt": "2017-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Workflows
GET`/workflows`

Return a list of all Workflows.

POST https://api.web1on1.chat/v2/workflows

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Automotive - Generic",
  "enabled": true,
  "rules": [
    {
      "id": "58bc9aecd906223dcec36493",
      "conditions": {
        "any": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ],
        "all": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ]
      },
      "event": {
        "type": "enqueue",
        "params": {
          "name": "Sales",
          "channel": "58bc9aecd906223dcec36493",
          "delay": 20
        }
      },
      "priority": 1
    }
  ],
  "organizations": [
    "58bc9aecd906223dcec36495",
    "58bc9aecd906223dcec36493"
  ],
  "organizationTags": [
    "56467a06d9b082b0059151dc"
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Defaults to the API key owner."
    },
    "name": {
      "type": "string",
      "description": "Name of the Workflow."
    },
    "enabled": {
      "type": "boolean",
      "description": "Boolean to switch the workflow on or off.",
      "default": true
    },
    "rules": {
      "type": "array",
      "description": "An array of rules that are matched to facts."
    },
    "organizations": {
      "type": "array",
      "description": "List of Organization IDs to limit the workflow to."
    },
    "organizationTags": {
      "type": "array",
      "description": "List of OrganizationGroup IDs to limit the workflow to."
    }
  },
  "required": [
    "name"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /workflows/5877a5ecb6b1bc76263e0a85

Body

{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Automotive - Generic",
  "enabled": true,
  "rules": [
    {
      "id": "58bc9aecd906223dcec36493",
      "conditions": {
        "any": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ],
        "all": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ]
      },
      "event": {
        "type": "enqueue",
        "params": {
          "name": "Sales",
          "channel": "58bc9aecd906223dcec36493",
          "delay": 20
        }
      },
      "priority": 1
    }
  ],
  "organizations": [
    "58bc9aecd906223dcec36495",
    "58bc9aecd906223dcec36493"
  ],
  "organizationTags": [
    "56467a06d9b082b0059151dc"
  ],
  "createdAt": "2017-01-07T14:03:43Z",
  "updatedAt": "2017-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Workflow."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Defaults to the API key owner."
    },
    "name": {
      "type": "string",
      "description": "Name of the Workflow."
    },
    "enabled": {
      "type": "boolean",
      "description": "Boolean to switch the workflow on or off.",
      "default": true
    },
    "rules": {
      "type": "array",
      "description": "An array of rules that are matched to facts."
    },
    "organizations": {
      "type": "array",
      "description": "List of Organization IDs to limit the workflow to."
    },
    "organizationTags": {
      "type": "array",
      "description": "List of OrganizationGroup IDs to limit the workflow to."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Create a New Workflow
POST`/workflows`

You may create a Workflow using this action.

Workflow ¶

GET https://api.web1on1.chat/v2/workflows/workflow_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Automotive - Generic",
  "enabled": true,
  "rules": [
    {
      "id": "58bc9aecd906223dcec36493",
      "conditions": {
        "any": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ],
        "all": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ]
      },
      "event": {
        "type": "enqueue",
        "params": {
          "name": "Sales",
          "channel": "58bc9aecd906223dcec36493",
          "delay": 20
        }
      },
      "priority": 1
    }
  ],
  "organizations": [
    "58bc9aecd906223dcec36495",
    "58bc9aecd906223dcec36493"
  ],
  "organizationTags": [
    "56467a06d9b082b0059151dc"
  ],
  "createdAt": "2017-01-07T14:03:43Z",
  "updatedAt": "2017-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Workflow."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Defaults to the API key owner."
    },
    "name": {
      "type": "string",
      "description": "Name of the Workflow."
    },
    "enabled": {
      "type": "boolean",
      "description": "Boolean to switch the workflow on or off.",
      "default": true
    },
    "rules": {
      "type": "array",
      "description": "An array of rules that are matched to facts."
    },
    "organizations": {
      "type": "array",
      "description": "List of Organization IDs to limit the workflow to."
    },
    "organizationTags": {
      "type": "array",
      "description": "List of OrganizationGroup IDs to limit the workflow to."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Retrieve a Workflow
GET`/workflows/{workflow_id}`

Returns a specific Workflow.

URI Parameters

HideShow

workflow_id: string (required)
ID of the Workflow.

PATCH https://api.web1on1.chat/v2/workflows/workflow_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Automotive - Generic",
  "enabled": true,
  "rules": [
    {
      "id": "58bc9aecd906223dcec36493",
      "conditions": {
        "any": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ],
        "all": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ]
      },
      "event": {
        "type": "enqueue",
        "params": {
          "name": "Sales",
          "channel": "58bc9aecd906223dcec36493",
          "delay": 20
        }
      },
      "priority": 1
    }
  ],
  "organizations": [
    "58bc9aecd906223dcec36495",
    "58bc9aecd906223dcec36493"
  ],
  "organizationTags": [
    "56467a06d9b082b0059151dc"
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Defaults to the API key owner."
    },
    "name": {
      "type": "string",
      "description": "Name of the Workflow."
    },
    "enabled": {
      "type": "boolean",
      "description": "Boolean to switch the workflow on or off.",
      "default": true
    },
    "rules": {
      "type": "array",
      "description": "An array of rules that are matched to facts."
    },
    "organizations": {
      "type": "array",
      "description": "List of Organization IDs to limit the workflow to."
    },
    "organizationTags": {
      "type": "array",
      "description": "List of OrganizationGroup IDs to limit the workflow to."
    }
  },
  "required": [
    "name"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Automotive - Generic",
  "enabled": true,
  "rules": [
    {
      "id": "58bc9aecd906223dcec36493",
      "conditions": {
        "any": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ],
        "all": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ]
      },
      "event": {
        "type": "enqueue",
        "params": {
          "name": "Sales",
          "channel": "58bc9aecd906223dcec36493",
          "delay": 20
        }
      },
      "priority": 1
    }
  ],
  "organizations": [
    "58bc9aecd906223dcec36495",
    "58bc9aecd906223dcec36493"
  ],
  "organizationTags": [
    "56467a06d9b082b0059151dc"
  ],
  "createdAt": "2017-01-07T14:03:43Z",
  "updatedAt": "2017-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Workflow."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Defaults to the API key owner."
    },
    "name": {
      "type": "string",
      "description": "Name of the Workflow."
    },
    "enabled": {
      "type": "boolean",
      "description": "Boolean to switch the workflow on or off.",
      "default": true
    },
    "rules": {
      "type": "array",
      "description": "An array of rules that are matched to facts."
    },
    "organizations": {
      "type": "array",
      "description": "List of Organization IDs to limit the workflow to."
    },
    "organizationTags": {
      "type": "array",
      "description": "List of OrganizationGroup IDs to limit the workflow to."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update a Workflow
PATCH`/workflows/{workflow_id}`

Update a specific Workflow.

URI Parameters

HideShow

workflow_id: string (required)
ID of the Workflow.

DELETE https://api.web1on1.chat/v2/workflows/workflow_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses204

This response has no content.

Delete a Workflow
DELETE`/workflows/{workflow_id}`

Delete a Workflow.

URI Parameters

HideShow

workflow_id: string (required)
ID of the Workflow.

Workflow Rules ¶

GET https://api.web1on1.chat/v2/workflows/workflow_id/rules

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "58bc9aecd906223dcec36493",
    "conditions": {
      "any": [
        {
          "fact": "conversation.category",
          "operator": "match",
          "value": "Used Car",
          "path": ".meta"
        }
      ],
      "all": [
        {
          "fact": "conversation.category",
          "operator": "match",
          "value": "Used Car",
          "path": ".meta"
        }
      ]
    },
    "event": {
      "type": "enqueue",
      "params": {
        "name": "Sales",
        "channel": "58bc9aecd906223dcec36493",
        "delay": 20
      }
    },
    "priority": 1
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Retrieve all Workflow Rules
GET`/workflows/{workflow_id}/rules`

Returns all rule objects of a specific Workflow.

URI Parameters

HideShow

workflow_id: string (required)
ID of the Workflow.

POST https://api.web1on1.chat/v2/workflows/workflow_id/rules

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "id": "58bc9aecd906223dcec36493",
  "conditions": {
    "any": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ],
    "all": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ]
  },
  "event": {
    "type": "enqueue",
    "params": {
      "name": "Sales",
      "channel": "58bc9aecd906223dcec36493",
      "delay": 20
    }
  },
  "priority": 1
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Rule ID."
    },
    "conditions": {
      "type": "object",
      "properties": {
        "any": {
          "type": "array",
          "description": "List of conditions evaluates to true if any match."
        },
        "all": {
          "type": "array",
          "description": "List of conditions evaluates to true if all match."
        }
      },
      "description": "Rule conditions."
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Only `enqueue` is supported."
        },
        "params": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Event name."
            },
            "channel": {
              "type": "string",
              "description": "Channel ID of target channel."
            },
            "isLastRule": {
              "type": "boolean",
              "description": "Boolean indicating that no more rules will be processed if this rule matches.",
              "default": false
            },
            "delay": {
              "type": "number",
              "description": "Number of seconds to postpone processing (since the workflow was called)."
            }
          },
          "required": [
            "name",
            "channel"
          ],
          "description": "Event parameters."
        }
      },
      "required": [
        "type",
        "params"
      ],
      "description": "Rule event."
    },
    "priority": {
      "type": "number",
      "description": "Priority of the rule, from 1 (low) to 5 (high priority)."
    }
  },
  "required": [
    "id",
    "conditions",
    "event"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /workflows/5877a5ecb6b1bc76263e0a85/rules/58bc9aecd906223dcec36493

Body

{
  "id": "58bc9aecd906223dcec36493",
  "conditions": {
    "any": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ],
    "all": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ]
  },
  "event": {
    "type": "enqueue",
    "params": {
      "name": "Sales",
      "channel": "58bc9aecd906223dcec36493",
      "delay": 20
    }
  },
  "priority": 1
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Rule ID."
    },
    "conditions": {
      "type": "object",
      "properties": {
        "any": {
          "type": "array",
          "description": "List of conditions evaluates to true if any match."
        },
        "all": {
          "type": "array",
          "description": "List of conditions evaluates to true if all match."
        }
      },
      "description": "Rule conditions."
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Only `enqueue` is supported."
        },
        "params": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Event name."
            },
            "channel": {
              "type": "string",
              "description": "Channel ID of target channel."
            },
            "isLastRule": {
              "type": "boolean",
              "description": "Boolean indicating that no more rules will be processed if this rule matches.",
              "default": false
            },
            "delay": {
              "type": "number",
              "description": "Number of seconds to postpone processing (since the workflow was called)."
            }
          },
          "required": [
            "name",
            "channel"
          ],
          "description": "Event parameters."
        }
      },
      "required": [
        "type",
        "params"
      ],
      "description": "Rule event."
    },
    "priority": {
      "type": "number",
      "description": "Priority of the rule, from 1 (low) to 5 (high priority)."
    }
  },
  "required": [
    "id",
    "conditions",
    "event"
  ]
}

Add a rule to a workflow
POST`/workflows/{workflow_id}/rules`

You may add a rule to a Workflow using this action.

URI Parameters

HideShow

workflow_id: string (required)
ID of the Workflow.

GET https://api.web1on1.chat/v2/workflows/workflow_id/rules/rule_id

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "58bc9aecd906223dcec36493",
  "conditions": {
    "any": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ],
    "all": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ]
  },
  "event": {
    "type": "enqueue",
    "params": {
      "name": "Sales",
      "channel": "58bc9aecd906223dcec36493",
      "delay": 20
    }
  },
  "priority": 1
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Rule ID."
    },
    "conditions": {
      "type": "object",
      "properties": {
        "any": {
          "type": "array",
          "description": "List of conditions evaluates to true if any match."
        },
        "all": {
          "type": "array",
          "description": "List of conditions evaluates to true if all match."
        }
      },
      "description": "Rule conditions."
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Only `enqueue` is supported."
        },
        "params": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Event name."
            },
            "channel": {
              "type": "string",
              "description": "Channel ID of target channel."
            },
            "isLastRule": {
              "type": "boolean",
              "description": "Boolean indicating that no more rules will be processed if this rule matches.",
              "default": false
            },
            "delay": {
              "type": "number",
              "description": "Number of seconds to postpone processing (since the workflow was called)."
            }
          },
          "required": [
            "name",
            "channel"
          ],
          "description": "Event parameters."
        }
      },
      "required": [
        "type",
        "params"
      ],
      "description": "Rule event."
    },
    "priority": {
      "type": "number",
      "description": "Priority of the rule, from 1 (low) to 5 (high priority)."
    }
  },
  "required": [
    "id",
    "conditions",
    "event"
  ]
}

Retrieve a specific Workflow Rule
GET`/workflows/{workflow_id}/rules/{rule_id}`

Returns a specific rule object of a Workflow.

URI Parameters

HideShow

workflow_id: string (required)
ID of the Workflow.
rule_id: string (required)
ID of the Worflow rule.

PATCH https://api.web1on1.chat/v2/workflows/workflow_id/rules/rule_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "id": "58bc9aecd906223dcec36493",
  "conditions": {
    "any": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ],
    "all": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ]
  },
  "event": {
    "type": "enqueue",
    "params": {
      "name": "Sales",
      "channel": "58bc9aecd906223dcec36493",
      "delay": 20
    }
  },
  "priority": 1
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Rule ID."
    },
    "conditions": {
      "type": "object",
      "properties": {
        "any": {
          "type": "array",
          "description": "List of conditions evaluates to true if any match."
        },
        "all": {
          "type": "array",
          "description": "List of conditions evaluates to true if all match."
        }
      },
      "description": "Rule conditions."
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Only `enqueue` is supported."
        },
        "params": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Event name."
            },
            "channel": {
              "type": "string",
              "description": "Channel ID of target channel."
            },
            "isLastRule": {
              "type": "boolean",
              "description": "Boolean indicating that no more rules will be processed if this rule matches.",
              "default": false
            },
            "delay": {
              "type": "number",
              "description": "Number of seconds to postpone processing (since the workflow was called)."
            }
          },
          "required": [
            "name",
            "channel"
          ],
          "description": "Event parameters."
        }
      },
      "required": [
        "type",
        "params"
      ],
      "description": "Rule event."
    },
    "priority": {
      "type": "number",
      "description": "Priority of the rule, from 1 (low) to 5 (high priority)."
    }
  },
  "required": [
    "id",
    "conditions",
    "event"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "58bc9aecd906223dcec36493",
  "conditions": {
    "any": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ],
    "all": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ]
  },
  "event": {
    "type": "enqueue",
    "params": {
      "name": "Sales",
      "channel": "58bc9aecd906223dcec36493",
      "delay": 20
    }
  },
  "priority": 1
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Rule ID."
    },
    "conditions": {
      "type": "object",
      "properties": {
        "any": {
          "type": "array",
          "description": "List of conditions evaluates to true if any match."
        },
        "all": {
          "type": "array",
          "description": "List of conditions evaluates to true if all match."
        }
      },
      "description": "Rule conditions."
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Only `enqueue` is supported."
        },
        "params": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Event name."
            },
            "channel": {
              "type": "string",
              "description": "Channel ID of target channel."
            },
            "isLastRule": {
              "type": "boolean",
              "description": "Boolean indicating that no more rules will be processed if this rule matches.",
              "default": false
            },
            "delay": {
              "type": "number",
              "description": "Number of seconds to postpone processing (since the workflow was called)."
            }
          },
          "required": [
            "name",
            "channel"
          ],
          "description": "Event parameters."
        }
      },
      "required": [
        "type",
        "params"
      ],
      "description": "Rule event."
    },
    "priority": {
      "type": "number",
      "description": "Priority of the rule, from 1 (low) to 5 (high priority)."
    }
  },
  "required": [
    "id",
    "conditions",
    "event"
  ]
}

Update a Workflow Rule
PATCH`/workflows/{workflow_id}/rules/{rule_id}`

Update a specific Workflow rule.

URI Parameters

HideShow

workflow_id: string (required)
ID of the Workflow.
rule_id: string (required)
ID of the Worflow rule.

DELETE https://api.web1on1.chat/v2/workflows/workflow_id/rules/rule_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses204

This response has no content.

Remove a Rule from a Workflow
DELETE`/workflows/{workflow_id}/rules/{rule_id}`

Remove a rule from a Workflow.

URI Parameters

HideShow

workflow_id: string (required)
ID of the Workflow.
rule_id: string (required)
ID of the Worflow rule.

Knowledge Bases ¶

Organizational Knowledge Bases are collections of information resources (articles, events, business venues and files) that can be used by agents to serve themselves with the right information at the right time.

Knowledge Bases ¶

The Knowledge Bases API provides methods to manage collections of fields, articles, locations and events.

A Knowledge Base has the following attributes:

Property	Type	Description	Example
id	string	Unique identifier for the knowledge base	5656f3ca42fc302027eba5c6
name	string*	Name of the knowledge base	Company Info
description	string	Description of the knowledge base	General company information
meta	MetaParams	Free-form object of key-values, that will be passed on to external systems, eg in webhook data.	{MetaParams}
createdAt	string	ISO8601 date and time of when the knowledge base was created.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of when the knowledge base was last modified.	2016-01-07T14:03:43Z

GET https://api.web1on1.chat/v2/kbases

Requestsexample 1

Headers

Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "5656f3ca42fc302027eba5c6",
    "name": "Company Info",
    "description": "General company information",
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Knowledge Bases
GET`/kbases`

Return a list of all knowledge bases for the organization and sub-organizations.

POST https://api.web1on1.chat/v2/kbases

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "name": "Company Info",
  "description": "General company information",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name of the knowledge base"
    },
    "description": {
      "type": "string",
      "description": "Description of the knowledge base"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    }
  },
  "required": [
    "name"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /kbases/5656f3ca42fc302027eba5c6

Body

{
  "id": "5656f3ca42fc302027eba5c6",
  "name": "Company Info",
  "description": "General company information",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the knowledge base"
    },
    "name": {
      "type": "string",
      "description": "Name of the knowledge base"
    },
    "description": {
      "type": "string",
      "description": "Description of the knowledge base"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the knowledge base was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the knowledge base was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Create a new Knowledge Base
POST`/kbases`

You may create a knowledge base using this action.

Knowledge Base ¶

GET https://api.web1on1.chat/v2/kbases/kbase_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5656f3ca42fc302027eba5c6",
  "name": "Company Info",
  "description": "General company information",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the knowledge base"
    },
    "name": {
      "type": "string",
      "description": "Name of the knowledge base"
    },
    "description": {
      "type": "string",
      "description": "Description of the knowledge base"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the knowledge base was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the knowledge base was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Retrieve a Knowledge Base
GET`/kbases/{kbase_id}`

Returns a Knowledge Base.

URI Parameters

HideShow

kbase_id: string (required)
ID of the Knowledge Base.

PATCH https://api.web1on1.chat/v2/kbases/kbase_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "name": "Company Info",
  "description": "General company information",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name of the knowledge base"
    },
    "description": {
      "type": "string",
      "description": "Description of the knowledge base"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    }
  },
  "required": [
    "name"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5656f3ca42fc302027eba5c6",
  "name": "Company Info",
  "description": "General company information",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the knowledge base"
    },
    "name": {
      "type": "string",
      "description": "Name of the knowledge base"
    },
    "description": {
      "type": "string",
      "description": "Description of the knowledge base"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the knowledge base was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the knowledge base was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update a Knowledge Base
PATCH`/kbases/{kbase_id}`

Update a specific Knowledge Base.

URI Parameters

HideShow

kbase_id: string (required)
ID of the Knowledge Base.

DELETE https://api.web1on1.chat/v2/kbases/kbase_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses204

This response has no content.

Delete a Knowledge Base
DELETE`/kbases/{kbase_id}`

Delete a Knowledge Base, including all its sub-resources.

URI Parameters

HideShow

kbase_id: string (required)
ID of the Knowledge Base.

Knowledge Base Items ¶

Use the kbitems endpoint for searches across files, events and articles.

GET https://api.web1on1.chat/v2/kbitems?sort=&offset=&limit=&select=&q=&types=&kbase=&organization=&matchTag=

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "type": "article",
    "document": {
      "id": "56b9d54c59f2698e0ae9623c",
      "organization": "58bcbafb8547f04f68c14bdb",
      "kbase": "58bc9aecd906223dcec36495",
      "title": "Financial Lease Options",
      "description": "All about financial lease possibilities",
      "content": "Buy now, <strong>pay later</strong>.",
      "publicationDate": "2017-01-07T10:00:00Z",
      "archiveDate": "2017-01-14T14:00:00Z",
      "tags": [
        "cheap",
        "stuff"
      ],
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      },
      "updatedBy": "58bc9aecd906223dcec36495",
      "createdAt": "2016-01-07T14:03:43Z",
      "updatedAt": "2016-01-07T14:03:43Z"
    }
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Knowledge Base Items
GET`/kbitems{?sort,offset,limit,select,q,types,kbase,organization,matchTag}`

Return a list of all articles, events and files matching the search parameters.

Using the /kbitems endpoint serves two purposes:

aggregated queries across resource types
listing of shared knowledge resources

As with other resources, by default you only have access to kbitems in or below your organization. However, unlike other resources, organizations higher-up may decide to share kbitems by giving your organization viewing rights. They can do this by tagging kbitems with tags matching the tags set for your organization.

To view kbitems within your organization tree as well as (inclusive of) kbitems shared with you from higher-up, specify the matchTag parameter.

Consider the following requests, requested by a level-2 admin for organization 456 (orgPath 123#456) tagged foo,baz. Given four articles in existence (two shared by parent org, two owned by own org, and one owned by child org 789), “V” indicates the article showing up in results:

Article	/kbtitems	/kbtitems?matchTag=true	/kbtitems?organization=456	/kbtitems?matchTag=true&organization=456	/kbtitems?matchTag=true&organization=123
org/orgPath:123 tags:foo	-	V	-	-	V
org/orgPath:123 tags:bar,baz	-	V	-	-	V
org:456, orgPath:123#456	V	V	V	V	-
org:456, orgPath:123#456, tags:bar	V	V	V	V	-
org:789, orgPath:123#456#789	V	V	-	-	-

In contrast, a level-3 admin for organization 789 with the single organization.tags bar would receive the following for the same requests:

Article	/kbtitems	/kbtitems?matchTag=true	/kbtitems?organization=456	/kbtitems?matchTag=true&organization=456	/kbtitems?matchTag=true&organization=123
org/orgPath:123 tags:foo	-	-	-	-	-
org/orgPath:123 tags:bar,baz	-	V	-	-	V
org:456, orgPath:123#456	-	-	-	-	-
org:456, orgPath:123#456, tags:bar	-	V	-	V	-
org:789, orgPath:123#456#789	V	V	-	-	-

In short, adding matchTag will make your query inclusive of upper-level shared kbitems (while still applying other filters).

URI Parameters

HideShow

sort: string (optional)
Sort order.
offset: number (optional)
Pagination start. Default: 0. Maximum 1000.
limit: number (optional)
Number of results. Default: 200. Maximum 1000.
select: string (optional)
Field selection.
q: string (optional)
Search term.
kbase: string (optional)
ID of the Knowledge Base.
organization: string (optional)
ID of the Organization.
types: string (optional)
Comma-separated list of document types (article, file).
matchTag: string (optional)
Include shared kbitems.

Articles ¶

An Article is a structured document containing generic know-how. It has the following attributes:

Property	Type	Description	Example
id	string	Unique identifier for the article	56b9d54c59f2698e0ae9623c
organization	string	Organization ID of the owning organization.	58bcbafb8547f04f68c14bdb
kbase	string*	Knowledge base ID.	58bc9aecd906223dcec36495
title	string*	Article title	Financial Lease Options
description	string	Article description	All about financial lease possibilities
content	string*	Article body	Buy now, pay later.
publicationDate	string	Date of publication	2017-01-07T10:00:00Z
archiveDate	string	Date of archiving	2017-01-14T14:00:00Z
tags	array	Tags	[cheap]
meta	MetaParams	Free-form object of key-values, that will be passed on to external systems, eg in webhook data.	{MetaParams}
updatedBy	string	User ID of the user that created or last modified the resource. Defaults to the current API user.	58bc9aecd906223dcec36495
createdAt	string	ISO8601 date and time of article creation.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of article last modification.	2016-01-07T14:03:43Z

GET https://api.web1on1.chat/v2/articles?sort=&offset=&limit=&select=&populate=

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "56b9d54c59f2698e0ae9623c",
    "organization": "58bcbafb8547f04f68c14bdb",
    "kbase": "58bc9aecd906223dcec36495",
    "title": "Financial Lease Options",
    "description": "All about financial lease possibilities",
    "content": "Buy now, <strong>pay later</strong>.",
    "publicationDate": "2017-01-07T10:00:00Z",
    "archiveDate": "2017-01-14T14:00:00Z",
    "tags": [
      "cheap",
      "stuff"
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "updatedBy": "58bc9aecd906223dcec36495",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Articles
GET`/articles{?sort,offset,limit,select,populate}`

Return a list of articles. Aside from generic URI parameters listed, any property can be used to filter query results; example:

GET https://api.web1on1.chat/v2/articles?tags=[nl,de]&content=~brochure

URI Parameters

HideShow

sort: string (optional)
Sort order.
offset: number (optional)
Pagination start. Default: 0. Maximum 1000.
limit: number (optional)
Number of results. Default: 200. Maximum 1000.
select: string (optional)
Field selection.
populate: string (optional)
Field population.

POST https://api.web1on1.chat/v2/articles

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "58bc9aecd906223dcec36495",
  "title": "Financial Lease Options",
  "description": "All about financial lease possibilities",
  "content": "Buy now, <strong>pay later</strong>.",
  "publicationDate": "2017-01-07T10:00:00Z",
  "archiveDate": "2017-01-14T14:00:00Z",
  "tags": [
    "cheap",
    "stuff"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "title": {
      "type": "string",
      "description": "Article title"
    },
    "description": {
      "type": "string",
      "description": "Article description"
    },
    "content": {
      "type": "string",
      "description": "Article body"
    },
    "publicationDate": {
      "type": "string",
      "description": "Date of publication"
    },
    "archiveDate": {
      "type": "string",
      "description": "Date of archiving"
    },
    "tags": {
      "type": "array",
      "description": "Tags"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource. Defaults to the current API user."
    }
  },
  "required": [
    "kbase",
    "title",
    "content"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /kbases/5656f3ca42fc302027eba5c6/articles/56b9d54c59f2698e0ae9623c

Body

{
  "id": "56b9d54c59f2698e0ae9623c",
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "58bc9aecd906223dcec36495",
  "title": "Financial Lease Options",
  "description": "All about financial lease possibilities",
  "content": "Buy now, <strong>pay later</strong>.",
  "publicationDate": "2017-01-07T10:00:00Z",
  "archiveDate": "2017-01-14T14:00:00Z",
  "tags": [
    "cheap",
    "stuff"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the article"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "title": {
      "type": "string",
      "description": "Article title"
    },
    "description": {
      "type": "string",
      "description": "Article description"
    },
    "content": {
      "type": "string",
      "description": "Article body"
    },
    "publicationDate": {
      "type": "string",
      "description": "Date of publication"
    },
    "archiveDate": {
      "type": "string",
      "description": "Date of archiving"
    },
    "tags": {
      "type": "array",
      "description": "Tags"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource. Defaults to the current API user."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of article creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of article last modification."
    }
  },
  "required": [
    "kbase",
    "title",
    "content"
  ]
}

Create a new Article
POST`/articles`

You may create a article using this action.

Article ¶

GET https://api.web1on1.chat/v2/articles/article_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56b9d54c59f2698e0ae9623c",
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "58bc9aecd906223dcec36495",
  "title": "Financial Lease Options",
  "description": "All about financial lease possibilities",
  "content": "Buy now, <strong>pay later</strong>.",
  "publicationDate": "2017-01-07T10:00:00Z",
  "archiveDate": "2017-01-14T14:00:00Z",
  "tags": [
    "cheap",
    "stuff"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the article"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "title": {
      "type": "string",
      "description": "Article title"
    },
    "description": {
      "type": "string",
      "description": "Article description"
    },
    "content": {
      "type": "string",
      "description": "Article body"
    },
    "publicationDate": {
      "type": "string",
      "description": "Date of publication"
    },
    "archiveDate": {
      "type": "string",
      "description": "Date of archiving"
    },
    "tags": {
      "type": "array",
      "description": "Tags"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource. Defaults to the current API user."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of article creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of article last modification."
    }
  },
  "required": [
    "kbase",
    "title",
    "content"
  ]
}

Retrieve an Article
GET`/articles/{article_id}`

Returns a specific Article.

URI Parameters

HideShow

article_id: string (required)
ID of the Article.

PATCH https://api.web1on1.chat/v2/articles/article_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "58bc9aecd906223dcec36495",
  "title": "Financial Lease Options",
  "description": "All about financial lease possibilities",
  "content": "Buy now, <strong>pay later</strong>.",
  "publicationDate": "2017-01-07T10:00:00Z",
  "archiveDate": "2017-01-14T14:00:00Z",
  "tags": [
    "cheap",
    "stuff"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "title": {
      "type": "string",
      "description": "Article title"
    },
    "description": {
      "type": "string",
      "description": "Article description"
    },
    "content": {
      "type": "string",
      "description": "Article body"
    },
    "publicationDate": {
      "type": "string",
      "description": "Date of publication"
    },
    "archiveDate": {
      "type": "string",
      "description": "Date of archiving"
    },
    "tags": {
      "type": "array",
      "description": "Tags"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource. Defaults to the current API user."
    }
  },
  "required": [
    "kbase",
    "title",
    "content"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56b9d54c59f2698e0ae9623c",
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "58bc9aecd906223dcec36495",
  "title": "Financial Lease Options",
  "description": "All about financial lease possibilities",
  "content": "Buy now, <strong>pay later</strong>.",
  "publicationDate": "2017-01-07T10:00:00Z",
  "archiveDate": "2017-01-14T14:00:00Z",
  "tags": [
    "cheap",
    "stuff"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the article"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "title": {
      "type": "string",
      "description": "Article title"
    },
    "description": {
      "type": "string",
      "description": "Article description"
    },
    "content": {
      "type": "string",
      "description": "Article body"
    },
    "publicationDate": {
      "type": "string",
      "description": "Date of publication"
    },
    "archiveDate": {
      "type": "string",
      "description": "Date of archiving"
    },
    "tags": {
      "type": "array",
      "description": "Tags"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource. Defaults to the current API user."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of article creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of article last modification."
    }
  },
  "required": [
    "kbase",
    "title",
    "content"
  ]
}

Update an Article
PATCH`/articles/{article_id}`

Update a specific Article.

URI Parameters

HideShow

article_id: string (required)
ID of the Article.

DELETE https://api.web1on1.chat/v2/articles/article_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses204

This response has no content.

Delete an Article
DELETE`/articles/{article_id}`

Delete an Article.

URI Parameters

HideShow

article_id: string (required)
ID of the Article.

Locations ¶

Office locations or other type of business venues can be managed using the Locations resource. It has the following properties:

Property	Type	Description	Example
id	string	Unique identifier for the business venue	56446de3c661e2e56efdb0ad
organization	string	Organization ID of the owning organization.	58bcbafb8547f04f68c14bdb
kbase	string*	Knowledge base ID.	58bc9aecd906223dcec36495
name	string*	Location name	Staples Centre
gplacesId	string	Google Places API - Place ID	ElMxNjIsIExhbmUgTnVtYmVyIDcsIEJsb…
description	string	Office location description	Staples HQ
streetAddress	string	Address street name	Downing street
streetNumber	string	Address street number	10
postalCode	string	Address location zip/postal code	SW1A 2AA
addressLocality	string	City or town	London
addressRegion	string	Region	London
addressCountry	string	ISO 3166-1 alpha-2 2-letter country code of address location.	UK
telephone	string	Office location telephone number	+3120669988
email	string	Office location email address	staples@example.com
url	string	URL of office location web page	http://example.com
latitude	number	Latitude of office location	52.366779
longitude	number	Longitude of office location	4.899296
officeHours	OfficeHours	Weekday schedule of office hours	{OfficeHours}
departments	array	List of deparments for this location	[{Deparment Full}]
tags	array	Keywords	[lease]
meta	MetaParams	Free-form object of key-values, that will be passed on to external systems, eg in webhook data.	{MetaParams}
updatedBy	string*	User ID of the user that created or last modified the resource.	58bc9aecd906223dcec36495
createdAt	string	ISO8601 date and time of Office creation.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of Office last modification.	2016-01-07T14:03:43Z

Address field name conventions are adapted from JSON-LD standards as specified at Schema.org.

https://schema.org/PostalAddress

GET https://api.web1on1.chat/v2/kbases/kbase_id/locations

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "56446de3c661e2e56efdb0ad",
    "organization": "58bcbafb8547f04f68c14bdb",
    "kbase": "58bc9aecd906223dcec36495",
    "name": "Staples Centre",
    "gplacesId": "ElMxNjIsIExhbmUgTnVtYmVyIDcsIEJsb...",
    "description": "Staples HQ",
    "streetAddress": "Downing street",
    "streetNumber": "10",
    "postalCode": "SW1A 2AA",
    "addressLocality": "London",
    "addressRegion": "London",
    "addressCountry": "UK",
    "telephone": "+3120669988",
    "email": "staples@example.com",
    "url": "http://example.com",
    "latitude": 52.366779,
    "longitude": 4.899296,
    "officeHours": {
      "mon": "09:00-17:00",
      "tue": "09:00-17:00",
      "wed": "09:00-17:00",
      "thu": "09:00-17:00",
      "fri": "09:00-17:00",
      "sat": "09:00-17:00",
      "sun": "09:00-17:00"
    },
    "departments": [
      {
        "id": "5877ff19276f4e04db18e330",
        "name": "Sales",
        "externalId':": "Hello, world!",
        "type": "sales",
        "channel": "58bc9aecd906223dcec36493",
        "brands": [
          "Audi",
          "BMW"
        ],
        "emails": [
          "support@example.com",
          "help@example.com"
        ],
        "meta": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "tags": [
      "lease",
      "used"
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "updatedBy": "58bc9aecd906223dcec36495",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Locations
GET`/kbases/{kbase_id}/locations`

Return a list of all locations.

URI Parameters

HideShow

kbase_id: string (required)
ID of the Knowledge Base.

POST https://api.web1on1.chat/v2/kbases/kbase_id/locations

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "58bc9aecd906223dcec36495",
  "name": "Staples Centre",
  "gplacesId": "ElMxNjIsIExhbmUgTnVtYmVyIDcsIEJsb...",
  "description": "Staples HQ",
  "streetAddress": "Downing street",
  "streetNumber": "10",
  "postalCode": "SW1A 2AA",
  "addressLocality": "London",
  "addressRegion": "London",
  "addressCountry": "UK",
  "telephone": "+3120669988",
  "email": "staples@example.com",
  "url": "http://example.com",
  "latitude": 52.366779,
  "longitude": 4.899296,
  "officeHours": {
    "mon": "09:00-17:00",
    "tue": "09:00-17:00",
    "wed": "09:00-17:00",
    "thu": "09:00-17:00",
    "fri": "09:00-17:00",
    "sat": "09:00-17:00",
    "sun": "09:00-17:00"
  },
  "departments": [
    {
      "id": "5877ff19276f4e04db18e330",
      "name": "Sales",
      "externalId':": "Hello, world!",
      "type": "sales",
      "channel": "58bc9aecd906223dcec36493",
      "brands": [
        "Audi",
        "BMW"
      ],
      "emails": [
        "support@example.com",
        "help@example.com"
      ],
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "tags": [
    "lease",
    "used"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "name": {
      "type": "string",
      "description": "Location name"
    },
    "gplacesId": {
      "type": "string",
      "description": "Google Places API - Place ID"
    },
    "description": {
      "type": "string",
      "description": "Office location description"
    },
    "streetAddress": {
      "type": "string",
      "description": "Address street name"
    },
    "streetNumber": {
      "type": "string",
      "description": "Address street number"
    },
    "postalCode": {
      "type": "string",
      "description": "Address location zip/postal code"
    },
    "addressLocality": {
      "type": "string",
      "description": "City or town"
    },
    "addressRegion": {
      "type": "string",
      "description": "Region"
    },
    "addressCountry": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 2-letter country code of address location."
    },
    "telephone": {
      "type": "string",
      "description": "Office location telephone number"
    },
    "email": {
      "type": "string",
      "description": "Office location email address"
    },
    "url": {
      "type": "string",
      "description": "URL of office location web page"
    },
    "latitude": {
      "type": "number",
      "description": "Latitude of office location"
    },
    "longitude": {
      "type": "number",
      "description": "Longitude of office location"
    },
    "officeHours": {
      "type": "object",
      "properties": {
        "mon": {
          "type": "string",
          "description": "Monday"
        },
        "tue": {
          "type": "string",
          "description": "Tuesday"
        },
        "wed": {
          "type": "string",
          "description": "Wednesday"
        },
        "thu": {
          "type": "string",
          "description": "Thursday"
        },
        "fri": {
          "type": "string",
          "description": "Friday"
        },
        "sat": {
          "type": "string",
          "description": "Saturday"
        },
        "sun": {
          "type": "string",
          "description": "Sunday"
        }
      },
      "description": "Weekday schedule of office hours"
    },
    "departments": {
      "type": "array",
      "description": "List of deparments for this location"
    },
    "tags": {
      "type": "array",
      "description": "Keywords"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource."
    }
  },
  "required": [
    "kbase",
    "name",
    "updatedBy"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /kbases/5656f3ca42fc302027eba5c6/locations/56446de3c661e2e56efdb0ad

Body

{
  "id": "56446de3c661e2e56efdb0ad",
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "58bc9aecd906223dcec36495",
  "name": "Staples Centre",
  "gplacesId": "ElMxNjIsIExhbmUgTnVtYmVyIDcsIEJsb...",
  "description": "Staples HQ",
  "streetAddress": "Downing street",
  "streetNumber": "10",
  "postalCode": "SW1A 2AA",
  "addressLocality": "London",
  "addressRegion": "London",
  "addressCountry": "UK",
  "telephone": "+3120669988",
  "email": "staples@example.com",
  "url": "http://example.com",
  "latitude": 52.366779,
  "longitude": 4.899296,
  "officeHours": {
    "mon": "09:00-17:00",
    "tue": "09:00-17:00",
    "wed": "09:00-17:00",
    "thu": "09:00-17:00",
    "fri": "09:00-17:00",
    "sat": "09:00-17:00",
    "sun": "09:00-17:00"
  },
  "departments": [
    {
      "id": "5877ff19276f4e04db18e330",
      "name": "Sales",
      "externalId':": "Hello, world!",
      "type": "sales",
      "channel": "58bc9aecd906223dcec36493",
      "brands": [
        "Audi",
        "BMW"
      ],
      "emails": [
        "support@example.com",
        "help@example.com"
      ],
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "tags": [
    "lease",
    "used"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the business venue"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "name": {
      "type": "string",
      "description": "Location name"
    },
    "gplacesId": {
      "type": "string",
      "description": "Google Places API - Place ID"
    },
    "description": {
      "type": "string",
      "description": "Office location description"
    },
    "streetAddress": {
      "type": "string",
      "description": "Address street name"
    },
    "streetNumber": {
      "type": "string",
      "description": "Address street number"
    },
    "postalCode": {
      "type": "string",
      "description": "Address location zip/postal code"
    },
    "addressLocality": {
      "type": "string",
      "description": "City or town"
    },
    "addressRegion": {
      "type": "string",
      "description": "Region"
    },
    "addressCountry": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 2-letter country code of address location."
    },
    "telephone": {
      "type": "string",
      "description": "Office location telephone number"
    },
    "email": {
      "type": "string",
      "description": "Office location email address"
    },
    "url": {
      "type": "string",
      "description": "URL of office location web page"
    },
    "latitude": {
      "type": "number",
      "description": "Latitude of office location"
    },
    "longitude": {
      "type": "number",
      "description": "Longitude of office location"
    },
    "officeHours": {
      "type": "object",
      "properties": {
        "mon": {
          "type": "string",
          "description": "Monday"
        },
        "tue": {
          "type": "string",
          "description": "Tuesday"
        },
        "wed": {
          "type": "string",
          "description": "Wednesday"
        },
        "thu": {
          "type": "string",
          "description": "Thursday"
        },
        "fri": {
          "type": "string",
          "description": "Friday"
        },
        "sat": {
          "type": "string",
          "description": "Saturday"
        },
        "sun": {
          "type": "string",
          "description": "Sunday"
        }
      },
      "description": "Weekday schedule of office hours"
    },
    "departments": {
      "type": "array",
      "description": "List of deparments for this location"
    },
    "tags": {
      "type": "array",
      "description": "Keywords"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of Office creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of Office last modification."
    }
  },
  "required": [
    "kbase",
    "name",
    "updatedBy"
  ]
}

Create a new Location
POST`/kbases/{kbase_id}/locations`

You may create a location using this action.

URI Parameters

HideShow

kbase_id: string (required)
ID of the Knowledge Base.

Location ¶

GET https://api.web1on1.chat/v2/kbases/kbase_id/locations/location_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56446de3c661e2e56efdb0ad",
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "58bc9aecd906223dcec36495",
  "name": "Staples Centre",
  "gplacesId": "ElMxNjIsIExhbmUgTnVtYmVyIDcsIEJsb...",
  "description": "Staples HQ",
  "streetAddress": "Downing street",
  "streetNumber": "10",
  "postalCode": "SW1A 2AA",
  "addressLocality": "London",
  "addressRegion": "London",
  "addressCountry": "UK",
  "telephone": "+3120669988",
  "email": "staples@example.com",
  "url": "http://example.com",
  "latitude": 52.366779,
  "longitude": 4.899296,
  "officeHours": {
    "mon": "09:00-17:00",
    "tue": "09:00-17:00",
    "wed": "09:00-17:00",
    "thu": "09:00-17:00",
    "fri": "09:00-17:00",
    "sat": "09:00-17:00",
    "sun": "09:00-17:00"
  },
  "departments": [
    {
      "id": "5877ff19276f4e04db18e330",
      "name": "Sales",
      "externalId':": "Hello, world!",
      "type": "sales",
      "channel": "58bc9aecd906223dcec36493",
      "brands": [
        "Audi",
        "BMW"
      ],
      "emails": [
        "support@example.com",
        "help@example.com"
      ],
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "tags": [
    "lease",
    "used"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the business venue"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "name": {
      "type": "string",
      "description": "Location name"
    },
    "gplacesId": {
      "type": "string",
      "description": "Google Places API - Place ID"
    },
    "description": {
      "type": "string",
      "description": "Office location description"
    },
    "streetAddress": {
      "type": "string",
      "description": "Address street name"
    },
    "streetNumber": {
      "type": "string",
      "description": "Address street number"
    },
    "postalCode": {
      "type": "string",
      "description": "Address location zip/postal code"
    },
    "addressLocality": {
      "type": "string",
      "description": "City or town"
    },
    "addressRegion": {
      "type": "string",
      "description": "Region"
    },
    "addressCountry": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 2-letter country code of address location."
    },
    "telephone": {
      "type": "string",
      "description": "Office location telephone number"
    },
    "email": {
      "type": "string",
      "description": "Office location email address"
    },
    "url": {
      "type": "string",
      "description": "URL of office location web page"
    },
    "latitude": {
      "type": "number",
      "description": "Latitude of office location"
    },
    "longitude": {
      "type": "number",
      "description": "Longitude of office location"
    },
    "officeHours": {
      "type": "object",
      "properties": {
        "mon": {
          "type": "string",
          "description": "Monday"
        },
        "tue": {
          "type": "string",
          "description": "Tuesday"
        },
        "wed": {
          "type": "string",
          "description": "Wednesday"
        },
        "thu": {
          "type": "string",
          "description": "Thursday"
        },
        "fri": {
          "type": "string",
          "description": "Friday"
        },
        "sat": {
          "type": "string",
          "description": "Saturday"
        },
        "sun": {
          "type": "string",
          "description": "Sunday"
        }
      },
      "description": "Weekday schedule of office hours"
    },
    "departments": {
      "type": "array",
      "description": "List of deparments for this location"
    },
    "tags": {
      "type": "array",
      "description": "Keywords"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of Office creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of Office last modification."
    }
  },
  "required": [
    "kbase",
    "name",
    "updatedBy"
  ]
}

Retrieve a Location
GET`/kbases/{kbase_id}/locations/{location_id}`

Returns a specific location or business venue.

URI Parameters

HideShow

kbase_id: string (required)
ID of the Knowledge Base.
location_id: string (required)
ID of the Location.

PATCH https://api.web1on1.chat/v2/kbases/kbase_id/locations/location_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "58bc9aecd906223dcec36495",
  "name": "Staples Centre",
  "gplacesId": "ElMxNjIsIExhbmUgTnVtYmVyIDcsIEJsb...",
  "description": "Staples HQ",
  "streetAddress": "Downing street",
  "streetNumber": "10",
  "postalCode": "SW1A 2AA",
  "addressLocality": "London",
  "addressRegion": "London",
  "addressCountry": "UK",
  "telephone": "+3120669988",
  "email": "staples@example.com",
  "url": "http://example.com",
  "latitude": 52.366779,
  "longitude": 4.899296,
  "officeHours": {
    "mon": "09:00-17:00",
    "tue": "09:00-17:00",
    "wed": "09:00-17:00",
    "thu": "09:00-17:00",
    "fri": "09:00-17:00",
    "sat": "09:00-17:00",
    "sun": "09:00-17:00"
  },
  "departments": [
    {
      "id": "5877ff19276f4e04db18e330",
      "name": "Sales",
      "externalId':": "Hello, world!",
      "type": "sales",
      "channel": "58bc9aecd906223dcec36493",
      "brands": [
        "Audi",
        "BMW"
      ],
      "emails": [
        "support@example.com",
        "help@example.com"
      ],
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "tags": [
    "lease",
    "used"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "name": {
      "type": "string",
      "description": "Location name"
    },
    "gplacesId": {
      "type": "string",
      "description": "Google Places API - Place ID"
    },
    "description": {
      "type": "string",
      "description": "Office location description"
    },
    "streetAddress": {
      "type": "string",
      "description": "Address street name"
    },
    "streetNumber": {
      "type": "string",
      "description": "Address street number"
    },
    "postalCode": {
      "type": "string",
      "description": "Address location zip/postal code"
    },
    "addressLocality": {
      "type": "string",
      "description": "City or town"
    },
    "addressRegion": {
      "type": "string",
      "description": "Region"
    },
    "addressCountry": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 2-letter country code of address location."
    },
    "telephone": {
      "type": "string",
      "description": "Office location telephone number"
    },
    "email": {
      "type": "string",
      "description": "Office location email address"
    },
    "url": {
      "type": "string",
      "description": "URL of office location web page"
    },
    "latitude": {
      "type": "number",
      "description": "Latitude of office location"
    },
    "longitude": {
      "type": "number",
      "description": "Longitude of office location"
    },
    "officeHours": {
      "type": "object",
      "properties": {
        "mon": {
          "type": "string",
          "description": "Monday"
        },
        "tue": {
          "type": "string",
          "description": "Tuesday"
        },
        "wed": {
          "type": "string",
          "description": "Wednesday"
        },
        "thu": {
          "type": "string",
          "description": "Thursday"
        },
        "fri": {
          "type": "string",
          "description": "Friday"
        },
        "sat": {
          "type": "string",
          "description": "Saturday"
        },
        "sun": {
          "type": "string",
          "description": "Sunday"
        }
      },
      "description": "Weekday schedule of office hours"
    },
    "departments": {
      "type": "array",
      "description": "List of deparments for this location"
    },
    "tags": {
      "type": "array",
      "description": "Keywords"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource."
    }
  },
  "required": [
    "kbase",
    "name",
    "updatedBy"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56446de3c661e2e56efdb0ad",
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "58bc9aecd906223dcec36495",
  "name": "Staples Centre",
  "gplacesId": "ElMxNjIsIExhbmUgTnVtYmVyIDcsIEJsb...",
  "description": "Staples HQ",
  "streetAddress": "Downing street",
  "streetNumber": "10",
  "postalCode": "SW1A 2AA",
  "addressLocality": "London",
  "addressRegion": "London",
  "addressCountry": "UK",
  "telephone": "+3120669988",
  "email": "staples@example.com",
  "url": "http://example.com",
  "latitude": 52.366779,
  "longitude": 4.899296,
  "officeHours": {
    "mon": "09:00-17:00",
    "tue": "09:00-17:00",
    "wed": "09:00-17:00",
    "thu": "09:00-17:00",
    "fri": "09:00-17:00",
    "sat": "09:00-17:00",
    "sun": "09:00-17:00"
  },
  "departments": [
    {
      "id": "5877ff19276f4e04db18e330",
      "name": "Sales",
      "externalId':": "Hello, world!",
      "type": "sales",
      "channel": "58bc9aecd906223dcec36493",
      "brands": [
        "Audi",
        "BMW"
      ],
      "emails": [
        "support@example.com",
        "help@example.com"
      ],
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "tags": [
    "lease",
    "used"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the business venue"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "name": {
      "type": "string",
      "description": "Location name"
    },
    "gplacesId": {
      "type": "string",
      "description": "Google Places API - Place ID"
    },
    "description": {
      "type": "string",
      "description": "Office location description"
    },
    "streetAddress": {
      "type": "string",
      "description": "Address street name"
    },
    "streetNumber": {
      "type": "string",
      "description": "Address street number"
    },
    "postalCode": {
      "type": "string",
      "description": "Address location zip/postal code"
    },
    "addressLocality": {
      "type": "string",
      "description": "City or town"
    },
    "addressRegion": {
      "type": "string",
      "description": "Region"
    },
    "addressCountry": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 2-letter country code of address location."
    },
    "telephone": {
      "type": "string",
      "description": "Office location telephone number"
    },
    "email": {
      "type": "string",
      "description": "Office location email address"
    },
    "url": {
      "type": "string",
      "description": "URL of office location web page"
    },
    "latitude": {
      "type": "number",
      "description": "Latitude of office location"
    },
    "longitude": {
      "type": "number",
      "description": "Longitude of office location"
    },
    "officeHours": {
      "type": "object",
      "properties": {
        "mon": {
          "type": "string",
          "description": "Monday"
        },
        "tue": {
          "type": "string",
          "description": "Tuesday"
        },
        "wed": {
          "type": "string",
          "description": "Wednesday"
        },
        "thu": {
          "type": "string",
          "description": "Thursday"
        },
        "fri": {
          "type": "string",
          "description": "Friday"
        },
        "sat": {
          "type": "string",
          "description": "Saturday"
        },
        "sun": {
          "type": "string",
          "description": "Sunday"
        }
      },
      "description": "Weekday schedule of office hours"
    },
    "departments": {
      "type": "array",
      "description": "List of deparments for this location"
    },
    "tags": {
      "type": "array",
      "description": "Keywords"
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of Office creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of Office last modification."
    }
  },
  "required": [
    "kbase",
    "name",
    "updatedBy"
  ]
}

Update a Location
PATCH`/kbases/{kbase_id}/locations/{location_id}`

Update a specific location or business venue.

URI Parameters

HideShow

kbase_id: string (required)
ID of the Knowledge Base.
location_id: string (required)
ID of the Location.

DELETE https://api.web1on1.chat/v2/kbases/kbase_id/locations/location_id

Responses204

This response has no content.

Delete a Location
DELETE`/kbases/{kbase_id}/locations/{location_id}`

Delete a location or business venue.

URI Parameters

HideShow

kbase_id: string (required)
ID of the Knowledge Base.
location_id: string (required)
ID of the Location.

Files ¶

A File resource represents a PDF in Google Cloud Storage. Its attributes are:

Property	Type	Description	Example
id	string	Unique identifier for the file	5a1f59bc3cb294236bccc46b
organization	string	Organization ID of the owning organization.	58bcbafb8547f04f68c14bdb
kbase	string	Knowledge base ID.	59f6e64d0a55c74a7962727e
title	string	Optional document title	Acme Price List
filename	string	Document file name at Cloud Storage.	5a1f59bc3cb294236bccc46b.pdf
path	string	Full path at Cloud Storage.	kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf
url	string	Cloud Storage URL.	https://storage.googleapis.com/cs2-uploads/kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf
signedUrl	string	Signed Cloud Storage URL.	https://storage.googleapis.com/cs2-uploads/kbases%2F59f6e64d0a55c74a7962727e%2F5a1f59bc3cb294236bccc46b.pdf?GoogleAccessId=…&Expires=…&Signature=…
extension	string	File extension.	.pdf
mimetype	string	Document MIME type.	application/pdf
bytes	number	Document size in bytes.	1079242
originalName	string	Original file name on upload.	1711.05410.pdf
isIndexed	boolean	Flag indicating if PDF is indexed for search. Defaults to false.	false
isPublic	boolean	Flag indicating a PDF public/sharable to consumers. Defaults to false.	false
tags	array	Keywords.	[lease]
updatedBy	string	User ID of last editing user. Defaults to the authenticated API user.	aaa000000000000000000222
createdAt	string	ISO8601 date and time of file creation.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of file last modification.	2016-01-07T14:03:43Z

GET https://api.web1on1.chat/v2/files?sort=&offset=&limit=&select=

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "5a1f59bc3cb294236bccc46b",
    "organization": "58bcbafb8547f04f68c14bdb",
    "kbase": "59f6e64d0a55c74a7962727e",
    "title": "Acme Price List",
    "filename": "5a1f59bc3cb294236bccc46b.pdf",
    "path": "kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf",
    "url": "https://storage.googleapis.com/cs2-uploads/kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf",
    "signedUrl": "https://storage.googleapis.com/cs2-uploads/kbases%2F59f6e64d0a55c74a7962727e%2F5a1f59bc3cb294236bccc46b.pdf?GoogleAccessId=..&Expires=..&Signature=..",
    "extension": ".pdf",
    "mimetype": "application/pdf",
    "bytes": 1079242,
    "originalName": "1711.05410.pdf",
    "isIndexed": true,
    "isPublic": true,
    "tags": [
      "lease",
      "price"
    ],
    "updatedBy": "aaa000000000000000000222",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List all Files
GET`/files{?sort,offset,limit,select}`

Return a list of all files. Aside from generic URI parameters listed, any file property can be used to filter query results; example:

GET https://api.web1on1.chat/v2/files?tags=[nl,de]&title=~brochure

URI Parameters

HideShow

sort: string (optional)
Sort order.
offset: number (optional)
Pagination start. Default: 0. Maximum 1000.
limit: number (optional)
Number of results. Default: 200. Maximum 1000.
select: string (optional)
Field selection.

POST https://api.web1on1.chat/v2/files

Requestsexample 1

Headers

Content-Type: multipart/form-data;boundary=---BOUNDARY
Authorization: Bearer <token>

Body

---BOUNDARY
Content-Disposition: form-data; name="title"
Content-Type: text/plain

Price List 2017
---BOUNDARY--
Content-Disposition: form-data; name="file"; filename="pricelist.pdf"
Content-Type: application/pdf
Content-Transfer-Encoding: base64

/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIA
AhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEB
AAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AD//Z
-----BOUNDARY

Responses201

Headers

Content-Type: application/json; charset=utf-8
Location: /kbases/5656f3ca42fc302027eba5c6/files/562e1085955cf08132fff510

Body

{
  "id": "5a1f59bc3cb294236bccc46b",
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "59f6e64d0a55c74a7962727e",
  "title": "Acme Price List",
  "filename": "5a1f59bc3cb294236bccc46b.pdf",
  "path": "kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf",
  "url": "https://storage.googleapis.com/cs2-uploads/kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf",
  "signedUrl": "https://storage.googleapis.com/cs2-uploads/kbases%2F59f6e64d0a55c74a7962727e%2F5a1f59bc3cb294236bccc46b.pdf?GoogleAccessId=..&Expires=..&Signature=..",
  "extension": ".pdf",
  "mimetype": "application/pdf",
  "bytes": 1079242,
  "originalName": "1711.05410.pdf",
  "isIndexed": true,
  "isPublic": true,
  "tags": [
    "lease",
    "price"
  ],
  "updatedBy": "aaa000000000000000000222",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the file"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "title": {
      "type": "string",
      "description": "Optional document title"
    },
    "filename": {
      "type": "string",
      "description": "Document file name at Cloud Storage."
    },
    "path": {
      "type": "string",
      "description": "Full path at Cloud Storage."
    },
    "url": {
      "type": "string",
      "description": "Cloud Storage URL."
    },
    "signedUrl": {
      "type": "string",
      "description": "Signed Cloud Storage URL."
    },
    "extension": {
      "type": "string",
      "description": "File extension."
    },
    "mimetype": {
      "type": "string",
      "description": "Document MIME type."
    },
    "bytes": {
      "type": "number",
      "description": "Document size in bytes."
    },
    "originalName": {
      "type": "string",
      "description": "Original file name on upload."
    },
    "isIndexed": {
      "type": "boolean",
      "description": "Flag indicating if PDF is indexed for search.",
      "default": false
    },
    "isPublic": {
      "type": "boolean",
      "description": "Flag indicating a PDF public/sharable to consumers.",
      "default": false
    },
    "tags": {
      "type": "array",
      "description": "Keywords."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of last editing user. Defaults to the authenticated API user."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of file creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of file last modification."
    }
  }
}

Upload a new File
POST`/files`

Use this action to upload a PDF into the CDN.

File ¶

GET https://api.web1on1.chat/v2/files/file_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5a1f59bc3cb294236bccc46b",
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "59f6e64d0a55c74a7962727e",
  "title": "Acme Price List",
  "filename": "5a1f59bc3cb294236bccc46b.pdf",
  "path": "kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf",
  "url": "https://storage.googleapis.com/cs2-uploads/kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf",
  "signedUrl": "https://storage.googleapis.com/cs2-uploads/kbases%2F59f6e64d0a55c74a7962727e%2F5a1f59bc3cb294236bccc46b.pdf?GoogleAccessId=..&Expires=..&Signature=..",
  "extension": ".pdf",
  "mimetype": "application/pdf",
  "bytes": 1079242,
  "originalName": "1711.05410.pdf",
  "isIndexed": true,
  "isPublic": true,
  "tags": [
    "lease",
    "price"
  ],
  "updatedBy": "aaa000000000000000000222",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the file"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "title": {
      "type": "string",
      "description": "Optional document title"
    },
    "filename": {
      "type": "string",
      "description": "Document file name at Cloud Storage."
    },
    "path": {
      "type": "string",
      "description": "Full path at Cloud Storage."
    },
    "url": {
      "type": "string",
      "description": "Cloud Storage URL."
    },
    "signedUrl": {
      "type": "string",
      "description": "Signed Cloud Storage URL."
    },
    "extension": {
      "type": "string",
      "description": "File extension."
    },
    "mimetype": {
      "type": "string",
      "description": "Document MIME type."
    },
    "bytes": {
      "type": "number",
      "description": "Document size in bytes."
    },
    "originalName": {
      "type": "string",
      "description": "Original file name on upload."
    },
    "isIndexed": {
      "type": "boolean",
      "description": "Flag indicating if PDF is indexed for search.",
      "default": false
    },
    "isPublic": {
      "type": "boolean",
      "description": "Flag indicating a PDF public/sharable to consumers.",
      "default": false
    },
    "tags": {
      "type": "array",
      "description": "Keywords."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of last editing user. Defaults to the authenticated API user."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of file creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of file last modification."
    }
  }
}

Retrieve a File
GET`/files/{file_id}`

Returns a specific File.

URI Parameters

HideShow

file_id: string (required)
ID of the File.

PATCH https://api.web1on1.chat/v2/files/file_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "59f6e64d0a55c74a7962727e",
  "title": "Acme Price List",
  "filename": "5a1f59bc3cb294236bccc46b.pdf",
  "path": "kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf",
  "url": "https://storage.googleapis.com/cs2-uploads/kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf",
  "signedUrl": "https://storage.googleapis.com/cs2-uploads/kbases%2F59f6e64d0a55c74a7962727e%2F5a1f59bc3cb294236bccc46b.pdf?GoogleAccessId=..&Expires=..&Signature=..",
  "extension": ".pdf",
  "mimetype": "application/pdf",
  "bytes": 1079242,
  "originalName": "1711.05410.pdf",
  "isIndexed": true,
  "isPublic": true,
  "tags": [
    "lease",
    "price"
  ],
  "updatedBy": "aaa000000000000000000222"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "title": {
      "type": "string",
      "description": "Optional document title"
    },
    "filename": {
      "type": "string",
      "description": "Document file name at Cloud Storage."
    },
    "path": {
      "type": "string",
      "description": "Full path at Cloud Storage."
    },
    "url": {
      "type": "string",
      "description": "Cloud Storage URL."
    },
    "signedUrl": {
      "type": "string",
      "description": "Signed Cloud Storage URL."
    },
    "extension": {
      "type": "string",
      "description": "File extension."
    },
    "mimetype": {
      "type": "string",
      "description": "Document MIME type."
    },
    "bytes": {
      "type": "number",
      "description": "Document size in bytes."
    },
    "originalName": {
      "type": "string",
      "description": "Original file name on upload."
    },
    "isIndexed": {
      "type": "boolean",
      "description": "Flag indicating if PDF is indexed for search.",
      "default": false
    },
    "isPublic": {
      "type": "boolean",
      "description": "Flag indicating a PDF public/sharable to consumers.",
      "default": false
    },
    "tags": {
      "type": "array",
      "description": "Keywords."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of last editing user. Defaults to the authenticated API user."
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "5a1f59bc3cb294236bccc46b",
  "organization": "58bcbafb8547f04f68c14bdb",
  "kbase": "59f6e64d0a55c74a7962727e",
  "title": "Acme Price List",
  "filename": "5a1f59bc3cb294236bccc46b.pdf",
  "path": "kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf",
  "url": "https://storage.googleapis.com/cs2-uploads/kbases/59f6e64d0a55c74a7962727e/5a1f59bc3cb294236bccc46b.pdf",
  "signedUrl": "https://storage.googleapis.com/cs2-uploads/kbases%2F59f6e64d0a55c74a7962727e%2F5a1f59bc3cb294236bccc46b.pdf?GoogleAccessId=..&Expires=..&Signature=..",
  "extension": ".pdf",
  "mimetype": "application/pdf",
  "bytes": 1079242,
  "originalName": "1711.05410.pdf",
  "isIndexed": true,
  "isPublic": true,
  "tags": [
    "lease",
    "price"
  ],
  "updatedBy": "aaa000000000000000000222",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the file"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "kbase": {
      "type": "string",
      "description": "Knowledge base ID."
    },
    "title": {
      "type": "string",
      "description": "Optional document title"
    },
    "filename": {
      "type": "string",
      "description": "Document file name at Cloud Storage."
    },
    "path": {
      "type": "string",
      "description": "Full path at Cloud Storage."
    },
    "url": {
      "type": "string",
      "description": "Cloud Storage URL."
    },
    "signedUrl": {
      "type": "string",
      "description": "Signed Cloud Storage URL."
    },
    "extension": {
      "type": "string",
      "description": "File extension."
    },
    "mimetype": {
      "type": "string",
      "description": "Document MIME type."
    },
    "bytes": {
      "type": "number",
      "description": "Document size in bytes."
    },
    "originalName": {
      "type": "string",
      "description": "Original file name on upload."
    },
    "isIndexed": {
      "type": "boolean",
      "description": "Flag indicating if PDF is indexed for search.",
      "default": false
    },
    "isPublic": {
      "type": "boolean",
      "description": "Flag indicating a PDF public/sharable to consumers.",
      "default": false
    },
    "tags": {
      "type": "array",
      "description": "Keywords."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of last editing user. Defaults to the authenticated API user."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of file creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of file last modification."
    }
  }
}

Update a File
PATCH`/files/{file_id}`

Update a file.

URI Parameters

HideShow

file_id: string (required)
ID of the File.

DELETE https://api.web1on1.chat/v2/files/file_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses204

This response has no content.

Delete a File
DELETE`/files/{file_id}`

Delete a File.

URI Parameters

HideShow

file_id: string (required)
ID of the File.

WhatsApp Templates ¶

WhatsApp Templates can be managed using the watemplates resource. It has the following properties:

Property	Type	Description	Example
id	string	Unique identifier for the template	56b9d54c59f2698e0ae9623c
organization	string	Organization ID of the owning organization.	58bcbafb8547f04f68c14bdb
name	string*	The name of the message template with a maximum of 512 characters and only containing lowercase characters, numbers and underscores.	shipping_notification
category	enum*	The category of message template. Please see the Message Templates section of Facebook’s Business Management API Documentation for the list supported categories. One of ‘AUTHENTICATION’, ‘MARKET’, ‘UTILITY’. Defaults to UTILITY.	‘AUTHENTICATION’
language	string*	The language of the message template. Please see the Message Templates section of Facebook’s Business Management API Documentation for the list of supported languages.	en
components	array*	An array of components that make up the message template. Please see Message Template Components for more information.	[{WAComponent}]
meta	MetaParams	Free-form object of key-values, that will be passed on to external systems, eg in webhook data.	{MetaParams}
updatedBy	string	User ID of the user that created or last modified the resource. Defaults to the current API user.	58bc9aecd906223dcec36495
createdAt	string	ISO8601 date and time of template creation.	2016-01-07T14:03:43Z
updatedAt	string	ISO8601 date and time of template last modification.	2016-01-07T14:03:43Z

A component has the following structure:

Property	Type	Description	Example
type	enum*	The type of component. One of BODY, HEADER, FOOTER, BUTTONS. Defaults to BODY.	BODY
format	enum*	The format of the HEADER component. One of TEXT, IMAGE, DOCUMENT. Defaults to TEXT.	TEXT
text	string*	Text for the component. BODY text accepts a maximum of 1024 characters while HEADER and FOOTER text accepts a maximum of 60 characters.	Hello {givenName}, your invoice is {form.total}
examples	array	An array of strings with examples of each referenced variable, in the order they appear on the button’s text.	[Peter]
buttons	array*	An array of buttons that make up the BUTTONS component. Please see Message Template Component Buttons for more information.	[{WAButton}]

A button has these properties:

Property	Type	Description	Example
type	enum*	The type of component button. One of QUICK_REPLY, PHONE_NUMBER, URL. Defaults to BODY.	QUICK_REPLY
phoneNumber	string	The phoneNumber for a PHONE_NUMBER button. Required only if the buttons’s type is PHONE_NUMBER.	+312011111111
url	string	The url for a URL button. Required only if the buttons’s type is URL. Add a {{1}} suffix to make the URL dynamic.	https://example.com
examples	array	An array of strings with examples of each referenced variable, in the order they appear on the button’s text.	[$1]

GET https://api.web1on1.chat/v2/watemplates

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "56b9d54c59f2698e0ae9623c",
    "organization": "58bcbafb8547f04f68c14bdb",
    "name": "shipping_notification",
    "category": "'AUTHENTICATION'",
    "language": "en",
    "components": [
      {
        "type": "BODY",
        "format": "TEXT",
        "text": "Hello {givenName}, your invoice is {form.total}",
        "examples": [
          "Peter",
          "$1234.56"
        ],
        "buttons": [
          {
            "type": "QUICK_REPLY",
            "phoneNumber": "+312011111111",
            "url": "https://example.com",
            "examples": [
              "$1",
              "$2"
            ]
          }
        ]
      }
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "updatedBy": "58bc9aecd906223dcec36495",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All WhatsApp Templates
GET`/watemplates`

Return a list of all templates.

POST https://api.web1on1.chat/v2/watemplates

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "shipping_notification",
  "category": "'AUTHENTICATION'",
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "format": "TEXT",
      "text": "Hello {givenName}, your invoice is {form.total}",
      "examples": [
        "Peter",
        "$1234.56"
      ],
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "phoneNumber": "+312011111111",
          "url": "https://example.com",
          "examples": [
            "$1",
            "$2"
          ]
        }
      ]
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "name": {
      "type": "string",
      "description": "The name of the message template with a maximum of 512 characters and only containing lowercase characters, numbers and underscores."
    },
    "category": {
      "type": "string",
      "enum": [
        "'AUTHENTICATION'",
        "'MARKET'",
        "'UTILITY'"
      ],
      "default": "UTILITY",
      "description": "The category of message template. Please see the Message Templates section of Facebook’s Business Management API Documentation for the list supported categories."
    },
    "language": {
      "type": "string",
      "description": "The language of the message template. Please see the Message Templates section of Facebook’s Business Management API Documentation for the list of supported languages."
    },
    "components": {
      "type": "array",
      "description": "An array of components that make up the message template. Please see Message Template Components for more information."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource. Defaults to the current API user."
    }
  },
  "required": [
    "name",
    "category",
    "language",
    "components"
  ]
}

Responses201

Headers

Content-Type: application/json
Location: /watemplates/56446de3c661e2e56efdb0ad

Body

{
  "id": "56b9d54c59f2698e0ae9623c",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "shipping_notification",
  "category": "'AUTHENTICATION'",
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "format": "TEXT",
      "text": "Hello {givenName}, your invoice is {form.total}",
      "examples": [
        "Peter",
        "$1234.56"
      ],
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "phoneNumber": "+312011111111",
          "url": "https://example.com",
          "examples": [
            "$1",
            "$2"
          ]
        }
      ]
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the template"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "name": {
      "type": "string",
      "description": "The name of the message template with a maximum of 512 characters and only containing lowercase characters, numbers and underscores."
    },
    "category": {
      "type": "string",
      "enum": [
        "'AUTHENTICATION'",
        "'MARKET'",
        "'UTILITY'"
      ],
      "default": "UTILITY",
      "description": "The category of message template. Please see the Message Templates section of Facebook’s Business Management API Documentation for the list supported categories."
    },
    "language": {
      "type": "string",
      "description": "The language of the message template. Please see the Message Templates section of Facebook’s Business Management API Documentation for the list of supported languages."
    },
    "components": {
      "type": "array",
      "description": "An array of components that make up the message template. Please see Message Template Components for more information."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource. Defaults to the current API user."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of template creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of template last modification."
    }
  },
  "required": [
    "name",
    "category",
    "language",
    "components"
  ]
}

Create a new Template
POST`/watemplates`

You may create a location using this action.

Template ¶

GET https://api.web1on1.chat/v2/watemplates/template_id

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer <token>

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "56b9d54c59f2698e0ae9623c",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "shipping_notification",
  "category": "'AUTHENTICATION'",
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "format": "TEXT",
      "text": "Hello {givenName}, your invoice is {form.total}",
      "examples": [
        "Peter",
        "$1234.56"
      ],
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "phoneNumber": "+312011111111",
          "url": "https://example.com",
          "examples": [
            "$1",
            "$2"
          ]
        }
      ]
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "updatedBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the template"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization."
    },
    "name": {
      "type": "string",
      "description": "The name of the message template with a maximum of 512 characters and only containing lowercase characters, numbers and underscores."
    },
    "category": {
      "type": "string",
      "enum": [
        "'AUTHENTICATION'",
        "'MARKET'",
        "'UTILITY'"
      ],
      "default": "UTILITY",
      "description": "The category of message template. Please see the Message Templates section of Facebook’s Business Management API Documentation for the list supported categories."
    },
    "language": {
      "type": "string",
      "description": "The language of the message template. Please see the Message Templates section of Facebook’s Business Management API Documentation for the list of supported languages."
    },
    "components": {
      "type": "array",
      "description": "An array of components that make up the message template. Please see Message Template Components for more information."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "updatedBy": {
      "type": "string",
      "description": "User ID of the user that created or last modified the resource. Defaults to the current API user."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of template creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of template last modification."
    }
  },
  "required": [
    "name",
    "category",
    "language",
    "components"
  ]
}

Retrieve a Template
GET`/watemplates/{template_id}`

Returns a template.

URI Parameters

HideShow

template_id: string (required)
ID of the Template.

DELETE https://api.web1on1.chat/v2/watemplates/template_id

Responses204

This response has no content.

Delete a Template
DELETE`/watemplates/{template_id}`

Delete a WhatsApp template.

URI Parameters

HideShow

template_id: string (required)
ID of the Template.

Webhooks ¶

A Webhook payload has the following possible attributes:

id: 774ae370-02cc-11e7-ac41-c38ce8763025 (string) - The unique ID of the Webhook.
event: message.create.contact.form (string) - Event that triggered the webhook.
timestamp: 2017-03-07T00:24:45.607Z (string) - ISO8601 date and time of when the webhook post was sent.
organization: 5c138790ec944f05ff5f6d77 (string) - Organization owning the resource object.
activity: (object) - Activity Stream object.
data: (object) - Webhook payload.
timestamp: 2018-12-20T01:46:56.003Z (string) - Timestamp of the event.

The data payload contains one or more resources related to the event. The data.links object containing API URLs to primary resources (organization, conversation, message, contact and user) if relevant to the event.

An example of a webhook payload for a chat message in a contact conversation looks like this:

{
            "id": "774ae370-02cc-11e7-ac41-c38ce8763025",
            "timestamp": "2018-12-19T19:09:01Z",
            "event": "message.create.contact.chat",
            "organization": "5c138790ec944f05ff5f6d77",
            "activity": {
                "@context": "https://www.w3.org/ns/activitystreams",
                "type": "Create",
                "actor": {
                    "id": "http://localhost:3102/v2/users/5c1a99e410419f5fb88cb5f2",
                    "type": "Person"
                },
                "object": {
                    "id": "http://localhost:3102/v2/messages/5c1a974dabcdb128d0e90e93",
                    "type": "Object"
                },
                "published": "2018-12-19T19:09:01Z",
                "summary": "User Peter de Vos created Message undefined"
            },
            "data": {
                "conversation": { ...conversation object...},
                "message": { ...message object... },
                "links": { ...links to resources ... }
            }
        }

The structures of expanded documents below conform to the resources described elsewhere in this documentation. Any URL specified below is the URL that you setup on your system, so we can push updates.

The Request is what your system should expect and capture from our POST.
The Response is what we need to get back in order to complete the transaction.

Webhook Events ¶

Message Events

Messaging events trigger a webhook with a Message and Conversation in its payload:

Event	Description
message	A message in a conversation was affected.
message.update	A message in a conversation was updated.
message.delete	A message was deleted.
message.error	A message error occurred.

Message creation events are further augmented with the conversation type and the message type. Possible conversation types are:

contact
bot
agent
system

As an example, these are the message.create events for a contact conversation:

Event	Description
message.create.contact.chat	A chat message was added to a conversation.
message.create.contact.card	A card was added to a conversation.
message.create.contact.mention	A mention was added to a conversation.
message.create.contact.postback	A postback was added to a conversation.
message.create.contact.tag	A tag was added to a conversation.
message.create.contact.search	A search was added to a conversation.
message.create.contact.command	A command was added to a conversation.
message.create.contact.form	A form was added to a conversation.
message.create.contact.field	A field was added to a conversation.
message.create.contact.results	A results message was added to a conversation.
message.create.contact.report	A report was added to a conversation.
message.create.contact.status	A status message was added to a conversation.

User Events

The following events trigger a webhook with a User and optional Channel in its payload:

Event	Description
user.create	A new user was created.
user.invite	A user invite was sent.
user.update	A user was updated.
user.delete	A user was deleted.
user.login	A user logged in.
user.logout	A user logged out.
user.subscribe	A user subscribed to a channel.
user.unsubscribe	A user unsubscribed from a channel.

Other Resource Events

Additional resource actions trigger a webhook:

Resource	Events
conversation.*	create, update, delete
user.*	create, update, delete
bot.*	create, update, delete
botinstance.*	create, update, delete
organization.*	create, update, delete
contact.*	create, update, delete
service.*	create, update, delete
channel.*	create, update, delete
form.*	create, update, delete
workflow.*	create, update, delete
article.*	create, update, delete
event.*	create, update, delete
file.*	create, update, delete

POST https://api.web1on1.chat/v2/https:/your.domain/webhook

Requestsevent: conversation.messageevent: user.createevent: user.loginevent: user.logoutevent: user.subscribeevent: user.unsubscribe

Headers

Content-Type: application/json

Body

{
  "id": "774ae370-02cc-11e7-ac41-c38ce8763025",
  "timestamp": "2017-03-07T00:24:45.607Z",
  "event": "conversation.message",
  "data": {
    "conversation": {
      "organization": "58bcbafb8547f04f68c14bdb",
      "name": "Bonbowack Acerfuse",
      "type": "bot",
      "status": "queued",
      "category": "Used Car",
      "categoryIndex": 0,
      "language": "en",
      "contact": "58bc9aecd906223dcec36493",
      "messages": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    },
    "message": {
      "conversation": "58bc9aecd906223dcec36493",
      "text": "Hello ;-)",
      "type": "chat",
      "role": "contact",
      "isBackchannel": false,
      "contentType": "text/plain",
      "user": "58bc9aecd906223dcec36495",
      "service": "58bc9aecd906223dcec36493",
      "touchpoint": "web",
      "delay": 5000,
      "items": [
        {
          "title": "Tacos",
          "description": "Beef and cheese, hmmm...",
          "actions": [
            {
              "type": "link",
              "text": "Tacos",
              "iconUrl": "http://example.com/images/tag.png",
              "payload": "tacos",
              "uri": "http://example.org",
              "meta": {
                "someKey": "Some value",
                "anotherKey": "Some other value"
              }
            }
          ],
          "size": "compact",
          "mediaUrl": "http://example.org/image.png",
          "mediaType": "image/png"
        }
      ],
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "results": [
        {
          "form": "590d3af9e025187959e5e11c",
          "formName": "Identifiers",
          "type": "static",
          "values": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  },
  "links": {
    "organization": "https://api.web1on1.chat/v2/organizations/aaa111111111111111222333",
    "conversation": "https://api.web1on1.chat/v2/conversations/58bdfa88ea4b4e07c9972121",
    "message": "https://api.web1on1.chat/v2/messages/58bdfdcdea4b4e07c9972134",
    "contact": "https://api.web1on1.chat/v2/contacts/58bdfa88ea4b4e07c9972122",
    "user": "https://api.web1on1.chat/v2/users/58bdfa88ea4b4e07c9972121"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the webhook post."
    },
    "timestamp": {
      "type": "string",
      "description": "ISO8601 date and time of when the webhook post was sent."
    },
    "event": {
      "type": "string",
      "description": "The event that triggered the webhook."
    },
    "data": {
      "type": "object",
      "properties": {
        "conversation": {
          "type": "object",
          "properties": {
            "organization": {
              "type": "string",
              "description": "Organization ID, conversation owner."
            },
            "name": {
              "type": "string",
              "description": "Name for the conversation."
            },
            "type": {
              "type": "string",
              "enum": [
                "bot",
                "contact",
                "viewer",
                "agent",
                "admin",
                "system"
              ],
              "default": "bot",
              "description": "Conversation initiator type"
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "active",
                "closed"
              ],
              "default": "queued",
              "description": "Conversation status"
            },
            "category": {
              "type": "string",
              "description": "Category name."
            },
            "categoryIndex": {
              "type": "number",
              "description": "Index of the category in the organization's category list."
            },
            "language": {
              "type": "string",
              "description": "Conversation language."
            },
            "contact": {
              "type": "string",
              "description": "Contact ID of the visitor."
            },
            "messages": {
              "type": "array",
              "description": "An array of Message IDs for this conversation."
            },
            "meta": {
              "type": "object",
              "properties": {
                "someKey": {
                  "type": "string",
                  "description": "An example of a free-form key/value pair."
                },
                "anotherKey": {
                  "type": "string",
                  "description": "Another example of a free-form key/value pair."
                }
              },
              "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
            }
          },
          "description": "Conversation object."
        },
        "message": {
          "type": "object",
          "properties": {
            "conversation": {
              "type": "string",
              "description": "Conversation ID."
            },
            "text": {
              "type": "string",
              "description": "Message text or HTML, or the URL of a non-text contentType."
            },
            "type": {
              "type": "string",
              "enum": [
                "chat",
                "card",
                "postback",
                "mention",
                "tag",
                "search",
                "command",
                "form",
                "field",
                "results",
                "report",
                "status"
              ],
              "default": "chat",
              "description": "Message type"
            },
            "role": {
              "type": "string",
              "enum": [
                "contact",
                "agent",
                "bot",
                "system"
              ],
              "default": "bot",
              "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
            },
            "isBackchannel": {
              "type": "boolean",
              "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
              "default": true
            },
            "contentType": {
              "type": "string",
              "enum": [
                "text/plain",
                "text/html",
                "text/url",
                "image/png",
                "image/gif",
                "image/jpg",
                "image/jpeg",
                "application/pdf"
              ],
              "default": "text/plain",
              "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
            },
            "user": {
              "type": "string",
              "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
            },
            "service": {
              "type": "string",
              "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
            },
            "touchpoint": {
              "type": "string",
              "enum": [
                "web",
                "email",
                "sms",
                "facebook",
                "whatsapp"
              ],
              "default": "web",
              "description": "Touchpoint/platform source or target at service for this message."
            },
            "delay": {
              "type": "number",
              "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
            },
            "items": {
              "type": "array",
              "description": "An array of list items to present to participants, each item containing one or more actions."
            },
            "actions": {
              "type": "array",
              "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
            },
            "results": {
              "type": "array",
              "description": "An array of form results objects that were collected from messages with type `results`."
            },
            "meta": {
              "type": "object",
              "properties": {
                "someKey": {
                  "type": "string",
                  "description": "An example of a free-form key/value pair."
                },
                "anotherKey": {
                  "type": "string",
                  "description": "Another example of a free-form key/value pair."
                }
              },
              "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
            }
          },
          "required": [
            "conversation",
            "text"
          ],
          "description": "User object."
        }
      },
      "description": "Webhook payload."
    },
    "links": {
      "type": "object",
      "properties": {
        "organization": {
          "type": "string",
          "description": "Organization."
        },
        "conversation": {
          "type": "string",
          "description": "Conversation."
        },
        "message": {
          "type": "string",
          "description": "Message."
        },
        "contact": {
          "type": "string",
          "description": "Contact."
        },
        "user": {
          "type": "string",
          "description": "User."
        }
      },
      "required": [
        "organization",
        "conversation",
        "message",
        "contact",
        "user"
      ],
      "description": "Links to API resources."
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "status": "ok"
}

Headers

Content-Type: application/json

Body

{
  "id": "774ae370-02cc-11e7-ac41-c38ce8763025",
  "timestamp": "2017-03-07T00:24:45.607Z",
  "event": "user.create",
  "data": {
    "user": {
      "familyName": "Vries",
      "givenName": "Hans",
      "additionalName": "de",
      "displayName": "Hans de Vries",
      "email": "jeff@jeffdoe.com",
      "phone": "+31209876543",
      "password": "z3krUt",
      "avatar": "http://yoursite.com/images/avatar.png",
      "organization": "55dcf8aa048ee2227d4aa1a4",
      "role": "agent",
      "settings": {
        "timezone": "Europe/Amsterdam",
        "timezoneSet": true,
        "locale": "en",
        "localeSet": true,
        "audioOnChat": true,
        "audioOnMessage": true,
        "notifyOnChat": true,
        "notifyOnMessage": true,
        "tabdotNotify": true,
        "tabdotMessage": true,
        "pushNotify": true,
        "focusOnAccept": true,
        "notifications": [
          "technical",
          "billing",
          "reporting",
          "knowledge",
          "results"
        ],
        "cannedResponses": [
          "What is your name?",
          "Thank you {{ givenName }}"
        ]
      },
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      },
      "status": "queued"
    }
  },
  "links": {
    "user": "https://api.web1on1.chat/v2/users/58bdfa88ea4b4e07c9972121"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the webhook post."
    },
    "timestamp": {
      "type": "string",
      "description": "ISO8601 date and time of when the webhook post was sent."
    },
    "event": {
      "type": "string",
      "description": "The event that triggered the webhook."
    },
    "data": {
      "type": "object",
      "properties": {
        "user": {
          "type": "object",
          "properties": {
            "familyName": {
              "type": "string",
              "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
            },
            "givenName": {
              "type": "string",
              "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
            },
            "additionalName": {
              "type": "string",
              "description": "An additional name for a User, can be used for a middle name."
            },
            "displayName": {
              "type": "string",
              "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
            },
            "email": {
              "type": "string",
              "description": "Email address of the User, used to log in."
            },
            "phone": {
              "type": "string",
              "description": "User telephone number."
            },
            "password": {
              "type": "string",
              "description": "Login password for the User."
            },
            "avatar": {
              "type": "string",
              "description": "Avatar URL for the User."
            },
            "organization": {
              "type": "string",
              "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
            },
            "role": {
              "type": "string",
              "enum": [
                "agent",
                "admin",
                "owner"
              ],
              "default": "agent",
              "description": "The role of the agent within the organization."
            },
            "settings": {
              "type": "object",
              "properties": {
                "timezone": {
                  "type": "string",
                  "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
                },
                "timezoneSet": {
                  "type": "boolean",
                  "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
                  "default": false
                },
                "locale": {
                  "type": "string",
                  "enum": [
                    "en",
                    "nl",
                    "de",
                    "fr"
                  ],
                  "default": "en",
                  "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
                },
                "localeSet": {
                  "type": "boolean",
                  "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
                  "default": false
                },
                "audioOnChat": {
                  "type": "boolean",
                  "description": "Boolean to bleep on queue increments.",
                  "default": true
                },
                "audioOnMessage": {
                  "type": "boolean",
                  "description": "Boolean to bleep on new messages.",
                  "default": false
                },
                "notifyOnChat": {
                  "type": "boolean",
                  "description": "Boolean to show desktop notifications on queue increments.",
                  "default": false
                },
                "notifyOnMessage": {
                  "type": "boolean",
                  "description": "Boolean to show a desktop notification on each incoming message.",
                  "default": false
                },
                "tabdotNotify": {
                  "type": "boolean",
                  "description": "Boolean to show a browser tab notification on queued conversations.",
                  "default": true
                },
                "tabdotMessage": {
                  "type": "boolean",
                  "description": "Boolean to show a browser tab notification on unread messages.",
                  "default": true
                },
                "pushNotify": {
                  "type": "boolean",
                  "description": "Boolean to enable mobile push inbox notifications.",
                  "default": false
                },
                "focusOnAccept": {
                  "type": "boolean",
                  "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
                  "default": false
                },
                "notifications": {
                  "type": "array",
                  "description": "List of notification roles for the user."
                },
                "cannedResponses": {
                  "type": "array",
                  "description": "List of canned responses."
                }
              },
              "description": "User preferences."
            },
            "meta": {
              "type": "object",
              "properties": {
                "someKey": {
                  "type": "string",
                  "description": "An example of a free-form key/value pair."
                },
                "anotherKey": {
                  "type": "string",
                  "description": "Another example of a free-form key/value pair."
                }
              },
              "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "invited",
                "active",
                "archived"
              ],
              "default": "queued",
              "description": "The status of the user for given organization."
            }
          },
          "required": [
            "email"
          ],
          "description": "User object."
        }
      },
      "description": "Webhook payload."
    },
    "links": {
      "type": "object",
      "properties": {
        "user": {
          "type": "string",
          "description": "User."
        }
      },
      "required": [
        "user"
      ],
      "description": "Links to API resources."
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "status": "ok"
}

Headers

Content-Type: application/json

Body

{
  "id": "774ae370-02cc-11e7-ac41-c38ce8763025",
  "timestamp": "2017-03-07T00:24:45.607Z",
  "event": "user.login",
  "data": {
    "user": {
      "familyName": "Vries",
      "givenName": "Hans",
      "additionalName": "de",
      "displayName": "Hans de Vries",
      "email": "jeff@jeffdoe.com",
      "phone": "+31209876543",
      "password": "z3krUt",
      "avatar": "http://yoursite.com/images/avatar.png",
      "organization": "55dcf8aa048ee2227d4aa1a4",
      "role": "agent",
      "settings": {
        "timezone": "Europe/Amsterdam",
        "timezoneSet": true,
        "locale": "en",
        "localeSet": true,
        "audioOnChat": true,
        "audioOnMessage": true,
        "notifyOnChat": true,
        "notifyOnMessage": true,
        "tabdotNotify": true,
        "tabdotMessage": true,
        "pushNotify": true,
        "focusOnAccept": true,
        "notifications": [
          "technical",
          "billing",
          "reporting",
          "knowledge",
          "results"
        ],
        "cannedResponses": [
          "What is your name?",
          "Thank you {{ givenName }}"
        ]
      },
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      },
      "status": "queued"
    }
  },
  "links": {
    "user": "https://api.web1on1.chat/v2/users/58bdfa88ea4b4e07c9972121"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the webhook post."
    },
    "timestamp": {
      "type": "string",
      "description": "ISO8601 date and time of when the webhook post was sent."
    },
    "event": {
      "type": "string",
      "description": "The event that triggered the webhook."
    },
    "data": {
      "type": "object",
      "properties": {
        "user": {
          "type": "object",
          "properties": {
            "familyName": {
              "type": "string",
              "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
            },
            "givenName": {
              "type": "string",
              "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
            },
            "additionalName": {
              "type": "string",
              "description": "An additional name for a User, can be used for a middle name."
            },
            "displayName": {
              "type": "string",
              "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
            },
            "email": {
              "type": "string",
              "description": "Email address of the User, used to log in."
            },
            "phone": {
              "type": "string",
              "description": "User telephone number."
            },
            "password": {
              "type": "string",
              "description": "Login password for the User."
            },
            "avatar": {
              "type": "string",
              "description": "Avatar URL for the User."
            },
            "organization": {
              "type": "string",
              "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
            },
            "role": {
              "type": "string",
              "enum": [
                "agent",
                "admin",
                "owner"
              ],
              "default": "agent",
              "description": "The role of the agent within the organization."
            },
            "settings": {
              "type": "object",
              "properties": {
                "timezone": {
                  "type": "string",
                  "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
                },
                "timezoneSet": {
                  "type": "boolean",
                  "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
                  "default": false
                },
                "locale": {
                  "type": "string",
                  "enum": [
                    "en",
                    "nl",
                    "de",
                    "fr"
                  ],
                  "default": "en",
                  "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
                },
                "localeSet": {
                  "type": "boolean",
                  "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
                  "default": false
                },
                "audioOnChat": {
                  "type": "boolean",
                  "description": "Boolean to bleep on queue increments.",
                  "default": true
                },
                "audioOnMessage": {
                  "type": "boolean",
                  "description": "Boolean to bleep on new messages.",
                  "default": false
                },
                "notifyOnChat": {
                  "type": "boolean",
                  "description": "Boolean to show desktop notifications on queue increments.",
                  "default": false
                },
                "notifyOnMessage": {
                  "type": "boolean",
                  "description": "Boolean to show a desktop notification on each incoming message.",
                  "default": false
                },
                "tabdotNotify": {
                  "type": "boolean",
                  "description": "Boolean to show a browser tab notification on queued conversations.",
                  "default": true
                },
                "tabdotMessage": {
                  "type": "boolean",
                  "description": "Boolean to show a browser tab notification on unread messages.",
                  "default": true
                },
                "pushNotify": {
                  "type": "boolean",
                  "description": "Boolean to enable mobile push inbox notifications.",
                  "default": false
                },
                "focusOnAccept": {
                  "type": "boolean",
                  "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
                  "default": false
                },
                "notifications": {
                  "type": "array",
                  "description": "List of notification roles for the user."
                },
                "cannedResponses": {
                  "type": "array",
                  "description": "List of canned responses."
                }
              },
              "description": "User preferences."
            },
            "meta": {
              "type": "object",
              "properties": {
                "someKey": {
                  "type": "string",
                  "description": "An example of a free-form key/value pair."
                },
                "anotherKey": {
                  "type": "string",
                  "description": "Another example of a free-form key/value pair."
                }
              },
              "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "invited",
                "active",
                "archived"
              ],
              "default": "queued",
              "description": "The status of the user for given organization."
            }
          },
          "required": [
            "email"
          ],
          "description": "User object."
        }
      },
      "description": "Webhook payload."
    },
    "links": {
      "type": "object",
      "properties": {
        "user": {
          "type": "string",
          "description": "User."
        }
      },
      "required": [
        "user"
      ],
      "description": "Links to API resources."
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "status": "ok"
}

Headers

Content-Type: application/json

Body

{
  "id": "774ae370-02cc-11e7-ac41-c38ce8763025",
  "timestamp": "2017-03-07T00:24:45.607Z",
  "event": "user.logout",
  "data": {
    "user": {
      "familyName": "Vries",
      "givenName": "Hans",
      "additionalName": "de",
      "displayName": "Hans de Vries",
      "email": "jeff@jeffdoe.com",
      "phone": "+31209876543",
      "password": "z3krUt",
      "avatar": "http://yoursite.com/images/avatar.png",
      "organization": "55dcf8aa048ee2227d4aa1a4",
      "role": "agent",
      "settings": {
        "timezone": "Europe/Amsterdam",
        "timezoneSet": true,
        "locale": "en",
        "localeSet": true,
        "audioOnChat": true,
        "audioOnMessage": true,
        "notifyOnChat": true,
        "notifyOnMessage": true,
        "tabdotNotify": true,
        "tabdotMessage": true,
        "pushNotify": true,
        "focusOnAccept": true,
        "notifications": [
          "technical",
          "billing",
          "reporting",
          "knowledge",
          "results"
        ],
        "cannedResponses": [
          "What is your name?",
          "Thank you {{ givenName }}"
        ]
      },
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      },
      "status": "queued"
    }
  },
  "links": {
    "user": "https://api.web1on1.chat/v2/users/58bdfa88ea4b4e07c9972121"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the webhook post."
    },
    "timestamp": {
      "type": "string",
      "description": "ISO8601 date and time of when the webhook post was sent."
    },
    "event": {
      "type": "string",
      "description": "The event that triggered the webhook."
    },
    "data": {
      "type": "object",
      "properties": {
        "user": {
          "type": "object",
          "properties": {
            "familyName": {
              "type": "string",
              "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
            },
            "givenName": {
              "type": "string",
              "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
            },
            "additionalName": {
              "type": "string",
              "description": "An additional name for a User, can be used for a middle name."
            },
            "displayName": {
              "type": "string",
              "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
            },
            "email": {
              "type": "string",
              "description": "Email address of the User, used to log in."
            },
            "phone": {
              "type": "string",
              "description": "User telephone number."
            },
            "password": {
              "type": "string",
              "description": "Login password for the User."
            },
            "avatar": {
              "type": "string",
              "description": "Avatar URL for the User."
            },
            "organization": {
              "type": "string",
              "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
            },
            "role": {
              "type": "string",
              "enum": [
                "agent",
                "admin",
                "owner"
              ],
              "default": "agent",
              "description": "The role of the agent within the organization."
            },
            "settings": {
              "type": "object",
              "properties": {
                "timezone": {
                  "type": "string",
                  "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
                },
                "timezoneSet": {
                  "type": "boolean",
                  "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
                  "default": false
                },
                "locale": {
                  "type": "string",
                  "enum": [
                    "en",
                    "nl",
                    "de",
                    "fr"
                  ],
                  "default": "en",
                  "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
                },
                "localeSet": {
                  "type": "boolean",
                  "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
                  "default": false
                },
                "audioOnChat": {
                  "type": "boolean",
                  "description": "Boolean to bleep on queue increments.",
                  "default": true
                },
                "audioOnMessage": {
                  "type": "boolean",
                  "description": "Boolean to bleep on new messages.",
                  "default": false
                },
                "notifyOnChat": {
                  "type": "boolean",
                  "description": "Boolean to show desktop notifications on queue increments.",
                  "default": false
                },
                "notifyOnMessage": {
                  "type": "boolean",
                  "description": "Boolean to show a desktop notification on each incoming message.",
                  "default": false
                },
                "tabdotNotify": {
                  "type": "boolean",
                  "description": "Boolean to show a browser tab notification on queued conversations.",
                  "default": true
                },
                "tabdotMessage": {
                  "type": "boolean",
                  "description": "Boolean to show a browser tab notification on unread messages.",
                  "default": true
                },
                "pushNotify": {
                  "type": "boolean",
                  "description": "Boolean to enable mobile push inbox notifications.",
                  "default": false
                },
                "focusOnAccept": {
                  "type": "boolean",
                  "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
                  "default": false
                },
                "notifications": {
                  "type": "array",
                  "description": "List of notification roles for the user."
                },
                "cannedResponses": {
                  "type": "array",
                  "description": "List of canned responses."
                }
              },
              "description": "User preferences."
            },
            "meta": {
              "type": "object",
              "properties": {
                "someKey": {
                  "type": "string",
                  "description": "An example of a free-form key/value pair."
                },
                "anotherKey": {
                  "type": "string",
                  "description": "Another example of a free-form key/value pair."
                }
              },
              "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "invited",
                "active",
                "archived"
              ],
              "default": "queued",
              "description": "The status of the user for given organization."
            }
          },
          "required": [
            "email"
          ],
          "description": "User object."
        }
      },
      "description": "Webhook payload."
    },
    "links": {
      "type": "object",
      "properties": {
        "user": {
          "type": "string",
          "description": "User."
        }
      },
      "required": [
        "user"
      ],
      "description": "Links to API resources."
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "status": "ok"
}

Headers

Content-Type: application/json

Body

{
  "id": "774ae370-02cc-11e7-ac41-c38ce8763025",
  "timestamp": "2017-03-07T00:24:45.607Z",
  "event": "user.subscribe",
  "data": {
    "user": {
      "familyName": "Vries",
      "givenName": "Hans",
      "additionalName": "de",
      "displayName": "Hans de Vries",
      "email": "jeff@jeffdoe.com",
      "phone": "+31209876543",
      "password": "z3krUt",
      "avatar": "http://yoursite.com/images/avatar.png",
      "organization": "55dcf8aa048ee2227d4aa1a4",
      "role": "agent",
      "settings": {
        "timezone": "Europe/Amsterdam",
        "timezoneSet": true,
        "locale": "en",
        "localeSet": true,
        "audioOnChat": true,
        "audioOnMessage": true,
        "notifyOnChat": true,
        "notifyOnMessage": true,
        "tabdotNotify": true,
        "tabdotMessage": true,
        "pushNotify": true,
        "focusOnAccept": true,
        "notifications": [
          "technical",
          "billing",
          "reporting",
          "knowledge",
          "results"
        ],
        "cannedResponses": [
          "What is your name?",
          "Thank you {{ givenName }}"
        ]
      },
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      },
      "status": "queued"
    },
    "channel": {
      "name": "BC One",
      "organization": "55dcf8aa048ee2227d4aa1a4",
      "members": [
        {
          "user": "56467a06d9b082b0059151dc",
          "online": false,
          "bucket": "all"
        }
      ]
    }
  },
  "links": {
    "user": "https://api.web1on1.chat/v2/users/58bdfa88ea4b4e07c9972121",
    "channel": "https://api.web1on1.chat/v2/organizations/5a12329862eca153b1db4354"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the webhook post."
    },
    "timestamp": {
      "type": "string",
      "description": "ISO8601 date and time of when the webhook post was sent."
    },
    "event": {
      "type": "string",
      "description": "The event that triggered the webhook."
    },
    "data": {
      "type": "object",
      "properties": {
        "user": {
          "type": "object",
          "properties": {
            "familyName": {
              "type": "string",
              "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
            },
            "givenName": {
              "type": "string",
              "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
            },
            "additionalName": {
              "type": "string",
              "description": "An additional name for a User, can be used for a middle name."
            },
            "displayName": {
              "type": "string",
              "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
            },
            "email": {
              "type": "string",
              "description": "Email address of the User, used to log in."
            },
            "phone": {
              "type": "string",
              "description": "User telephone number."
            },
            "password": {
              "type": "string",
              "description": "Login password for the User."
            },
            "avatar": {
              "type": "string",
              "description": "Avatar URL for the User."
            },
            "organization": {
              "type": "string",
              "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
            },
            "role": {
              "type": "string",
              "enum": [
                "agent",
                "admin",
                "owner"
              ],
              "default": "agent",
              "description": "The role of the agent within the organization."
            },
            "settings": {
              "type": "object",
              "properties": {
                "timezone": {
                  "type": "string",
                  "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
                },
                "timezoneSet": {
                  "type": "boolean",
                  "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
                  "default": false
                },
                "locale": {
                  "type": "string",
                  "enum": [
                    "en",
                    "nl",
                    "de",
                    "fr"
                  ],
                  "default": "en",
                  "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
                },
                "localeSet": {
                  "type": "boolean",
                  "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
                  "default": false
                },
                "audioOnChat": {
                  "type": "boolean",
                  "description": "Boolean to bleep on queue increments.",
                  "default": true
                },
                "audioOnMessage": {
                  "type": "boolean",
                  "description": "Boolean to bleep on new messages.",
                  "default": false
                },
                "notifyOnChat": {
                  "type": "boolean",
                  "description": "Boolean to show desktop notifications on queue increments.",
                  "default": false
                },
                "notifyOnMessage": {
                  "type": "boolean",
                  "description": "Boolean to show a desktop notification on each incoming message.",
                  "default": false
                },
                "tabdotNotify": {
                  "type": "boolean",
                  "description": "Boolean to show a browser tab notification on queued conversations.",
                  "default": true
                },
                "tabdotMessage": {
                  "type": "boolean",
                  "description": "Boolean to show a browser tab notification on unread messages.",
                  "default": true
                },
                "pushNotify": {
                  "type": "boolean",
                  "description": "Boolean to enable mobile push inbox notifications.",
                  "default": false
                },
                "focusOnAccept": {
                  "type": "boolean",
                  "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
                  "default": false
                },
                "notifications": {
                  "type": "array",
                  "description": "List of notification roles for the user."
                },
                "cannedResponses": {
                  "type": "array",
                  "description": "List of canned responses."
                }
              },
              "description": "User preferences."
            },
            "meta": {
              "type": "object",
              "properties": {
                "someKey": {
                  "type": "string",
                  "description": "An example of a free-form key/value pair."
                },
                "anotherKey": {
                  "type": "string",
                  "description": "Another example of a free-form key/value pair."
                }
              },
              "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "invited",
                "active",
                "archived"
              ],
              "default": "queued",
              "description": "The status of the user for given organization."
            }
          },
          "required": [
            "email"
          ],
          "description": "User object."
        },
        "channel": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the Channel."
            },
            "organization": {
              "type": "string",
              "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
            },
            "members": {
              "type": "array",
              "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
            }
          },
          "required": [
            "name"
          ],
          "description": "Conversation object."
        }
      },
      "description": "Webhook payload."
    },
    "links": {
      "type": "object",
      "properties": {
        "user": {
          "type": "string",
          "description": "User."
        },
        "channel": {
          "type": "string",
          "description": "Channel."
        }
      },
      "required": [
        "user",
        "channel"
      ],
      "description": "Links to API resources."
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "status": "ok"
}

Headers

Content-Type: application/json

Body

{
  "id": "774ae370-02cc-11e7-ac41-c38ce8763025",
  "timestamp": "2017-03-07T00:24:45.607Z",
  "event": "user.unsubscribe",
  "data": {
    "user": {
      "familyName": "Vries",
      "givenName": "Hans",
      "additionalName": "de",
      "displayName": "Hans de Vries",
      "email": "jeff@jeffdoe.com",
      "phone": "+31209876543",
      "password": "z3krUt",
      "avatar": "http://yoursite.com/images/avatar.png",
      "organization": "55dcf8aa048ee2227d4aa1a4",
      "role": "agent",
      "settings": {
        "timezone": "Europe/Amsterdam",
        "timezoneSet": true,
        "locale": "en",
        "localeSet": true,
        "audioOnChat": true,
        "audioOnMessage": true,
        "notifyOnChat": true,
        "notifyOnMessage": true,
        "tabdotNotify": true,
        "tabdotMessage": true,
        "pushNotify": true,
        "focusOnAccept": true,
        "notifications": [
          "technical",
          "billing",
          "reporting",
          "knowledge",
          "results"
        ],
        "cannedResponses": [
          "What is your name?",
          "Thank you {{ givenName }}"
        ]
      },
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      },
      "status": "queued"
    },
    "channel": {
      "name": "BC One",
      "organization": "55dcf8aa048ee2227d4aa1a4",
      "members": [
        {
          "user": "56467a06d9b082b0059151dc",
          "online": false,
          "bucket": "all"
        }
      ]
    }
  },
  "links": {
    "user": "https://api.web1on1.chat/v2/users/58bdfa88ea4b4e07c9972121",
    "channel": "https://api.web1on1.chat/v2/organizations/5a12329862eca153b1db4354"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the webhook post."
    },
    "timestamp": {
      "type": "string",
      "description": "ISO8601 date and time of when the webhook post was sent."
    },
    "event": {
      "type": "string",
      "description": "The event that triggered the webhook."
    },
    "data": {
      "type": "object",
      "properties": {
        "user": {
          "type": "object",
          "properties": {
            "familyName": {
              "type": "string",
              "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
            },
            "givenName": {
              "type": "string",
              "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
            },
            "additionalName": {
              "type": "string",
              "description": "An additional name for a User, can be used for a middle name."
            },
            "displayName": {
              "type": "string",
              "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
            },
            "email": {
              "type": "string",
              "description": "Email address of the User, used to log in."
            },
            "phone": {
              "type": "string",
              "description": "User telephone number."
            },
            "password": {
              "type": "string",
              "description": "Login password for the User."
            },
            "avatar": {
              "type": "string",
              "description": "Avatar URL for the User."
            },
            "organization": {
              "type": "string",
              "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
            },
            "role": {
              "type": "string",
              "enum": [
                "agent",
                "admin",
                "owner"
              ],
              "default": "agent",
              "description": "The role of the agent within the organization."
            },
            "settings": {
              "type": "object",
              "properties": {
                "timezone": {
                  "type": "string",
                  "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
                },
                "timezoneSet": {
                  "type": "boolean",
                  "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
                  "default": false
                },
                "locale": {
                  "type": "string",
                  "enum": [
                    "en",
                    "nl",
                    "de",
                    "fr"
                  ],
                  "default": "en",
                  "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
                },
                "localeSet": {
                  "type": "boolean",
                  "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
                  "default": false
                },
                "audioOnChat": {
                  "type": "boolean",
                  "description": "Boolean to bleep on queue increments.",
                  "default": true
                },
                "audioOnMessage": {
                  "type": "boolean",
                  "description": "Boolean to bleep on new messages.",
                  "default": false
                },
                "notifyOnChat": {
                  "type": "boolean",
                  "description": "Boolean to show desktop notifications on queue increments.",
                  "default": false
                },
                "notifyOnMessage": {
                  "type": "boolean",
                  "description": "Boolean to show a desktop notification on each incoming message.",
                  "default": false
                },
                "tabdotNotify": {
                  "type": "boolean",
                  "description": "Boolean to show a browser tab notification on queued conversations.",
                  "default": true
                },
                "tabdotMessage": {
                  "type": "boolean",
                  "description": "Boolean to show a browser tab notification on unread messages.",
                  "default": true
                },
                "pushNotify": {
                  "type": "boolean",
                  "description": "Boolean to enable mobile push inbox notifications.",
                  "default": false
                },
                "focusOnAccept": {
                  "type": "boolean",
                  "description": "Boolean to activate conversations after accepting. Defaults to true for level2+ agents, false for top-level agents.",
                  "default": false
                },
                "notifications": {
                  "type": "array",
                  "description": "List of notification roles for the user."
                },
                "cannedResponses": {
                  "type": "array",
                  "description": "List of canned responses."
                }
              },
              "description": "User preferences."
            },
            "meta": {
              "type": "object",
              "properties": {
                "someKey": {
                  "type": "string",
                  "description": "An example of a free-form key/value pair."
                },
                "anotherKey": {
                  "type": "string",
                  "description": "Another example of a free-form key/value pair."
                }
              },
              "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "invited",
                "active",
                "archived"
              ],
              "default": "queued",
              "description": "The status of the user for given organization."
            }
          },
          "required": [
            "email"
          ],
          "description": "User object."
        },
        "channel": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the Channel."
            },
            "organization": {
              "type": "string",
              "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
            },
            "members": {
              "type": "array",
              "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
            }
          },
          "required": [
            "name"
          ],
          "description": "Conversation object."
        }
      },
      "description": "Webhook payload."
    },
    "links": {
      "type": "object",
      "properties": {
        "user": {
          "type": "string",
          "description": "User."
        },
        "channel": {
          "type": "string",
          "description": "Channel."
        }
      },
      "required": [
        "user",
        "channel"
      ],
      "description": "Links to API resources."
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "status": "ok"
}

Webhook Payloads
POST`/https:/your.domain/webhook`

Generated by aglio on 01 May 2025

API Endpoint

Authentication ¶

Time-based Tokens ¶

Headers

Body

Headers

Body

Schema

Create an Access TokenPOST/auth/token

Headers

Headers

Body

Schema

Refresh an Access TokenGET/auth/token?{refreshToken}

Messaging ¶

Conversations ¶

Headers

Headers

Body

Schema

List All ConversationsGET/conversations{?sort,offset,limit,select,populate,organization,type,status,categoryIndex,category,slug,participants.user,forms.form,results.form,language,meta.value,createdAt,updatedAt}

Headers

Body

Schema

Headers

Body

Schema

Create a new ConversationPOST/conversations

Conversation ¶

Headers

Headers

Body

Schema

Retrieve a ConversationGET/conversations/{conversation_id}

Headers

Body

Schema

Headers

Body

Schema

Update a ConversationPATCH/conversations/{conversation_id}

Delete a ConversationDELETE/conversations/{conversation_id}

Conversation Search ¶

Headers

Headers

Search for ConversationsGET/conversations/search?q

Conversation Links ¶

Headers

Headers

Body

Schema

List LinksGET/links/{?conversation}

Headers

Headers

Body

Schema

List Conversation LinksGET/conversations/{conversation_id}/links

Messages ¶

Message Items ¶

Action Buttons ¶

Headers

Headers

Body

Schema

List All MessagesGET/messages{?sort,offset,limit,select,populate,conversation,organization,type,role,isBackchannel,contentType,touchpoint,delay,user,text,meta,createdBy}

Headers

Headers

Body

Schema

List All Conversation MessagesGET/conversation/{conversation_id}/messages{?sort,offset,limit,select,populate,type,type,role,isBackchannel,contentType,touchpoint,delay,user,text,meta,createdBy}

Headers

Body

Schema

Headers

Body

Schema

Create a new MessagePOST/messages

Headers

Body

Schema

Create an Access Token
POST`/auth/token`

Refresh an Access Token
GET`/auth/token?{refreshToken}`

List All Conversations
GET`/conversations{?sort,offset,limit,select,populate,organization,type,status,categoryIndex,category,slug,participants.user,forms.form,results.form,language,meta.value,createdAt,updatedAt}`

Create a new Conversation
POST`/conversations`

Retrieve a Conversation
GET`/conversations/{conversation_id}`

Update a Conversation
PATCH`/conversations/{conversation_id}`

Delete a Conversation
DELETE`/conversations/{conversation_id}`

Search for Conversations
GET`/conversations/search?q`

List Links
GET`/links/{?conversation}`

List Conversation Links
GET`/conversations/{conversation_id}/links`

Message Items

Action Buttons

List All Messages
GET`/messages{?sort,offset,limit,select,populate,conversation,organization,type,role,isBackchannel,contentType,touchpoint,delay,user,text,meta,createdBy}`

List All Conversation Messages
GET`/conversation/{conversation_id}/messages{?sort,offset,limit,select,populate,type,type,role,isBackchannel,contentType,touchpoint,delay,user,text,meta,createdBy}`

Create a new Message
POST`/messages`

Create a new Conversation Message
POST`/conversation/{conversation_id}/messages`

Retrieve a Message
GET`/messages/{message_id}`

Update a Message
PATCH`/messages/{message_id}`

Delete a Message
DELETE`/messages/{message_id}`

Retrieve Attachments
GET`/conversations/{conversation_id}/attachments`

Upload Attachment
POST`/conversations/{conversation_id}/attachments`

Delete Attachments
DELETE`/conversations/{conversation_id}/attachments/{attachment_id}`

List Contacts
GET`/messages{?sort,offset,limit,select,populate,q,conversation,organization,profile.name,data.MyCarVIN,meta,createdBy}`

Retrieve a Contact
GET`/contacts/{contact_id}`

Update a Contact
PATCH`/contacts/{contact_id}`

List All Event Types
GET`/eventtypes`

Create a new Event Type
POST`/eventtypes`