# API reference
## Getting started
### Introduction
Welcome to the Pavior API reference. Our API is broken up into two parts:
- The **client API** can be used from directly inside your website. It allows you to programatically interact or take actions on behalf of the current user that has your website loaded.
- The **server API** can be used from a server you control. It allows you to programatically take actions on behalf of your entire team, across any objects within Pavior.
To the right, you will find relevant code examples for each section.
---
### Backward compatibility
Any part of our API may be changed in a backward-compatible way at any time. Backward compatibility means that new methods, objects, statuses, fields in responses, etc. may be added at any time, but existing ones **will never be renamed or removed.**
If there are backward-incompatible changes that we need to make, we will release a new API version. The previous API version will be maintained for a minimum of one year after releasing the new version.
---
## Client API
### Introduction
The Pavior client API can (and must) be used directly from your website. To use it, you must first include the Pavior `/embed` snippet, then immediately call the `init` function.
The `/embed` snippet is very small (< 1kb) and cached forever. We recommend you include it at the very top of your `` tag so Pavior starts working right away. If you defer the loading of this script, Pavior may not be able to identify problems that occur on your site before the script has finished loading.
Functions in Pavior are called using `Pavior(functionName, ...args)`. We use this calling scheme because it allows you to start using the API immediately, without waiting for our full API to load (the `/embed` script is responsible for loading the full API functionality).
```
```
---
## Client API commands
### init
The `init` call is required to be called before you can use any Pavior functionality on your website. It is used to:
1. Tell Pavior your team id
1. Set options
1. Set attributes on the visiting user
The `init` call has the following options:
| `teamId` | **Required**. You must set this to your team id. |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `doChat` | _Default:_ **false**. Setting this to true will show the chat bubble and enable full chat functionality. Setting it to false will hide the chat bubble and disable all chat functionality. |
| `doTimeTravel` | _Default:_ **false**. Setting this to true will enable time travel and other tracking features such as being able to add events for the user. Setting this to false will not record any part of the session, and will not allow submitting custom events for the user. |
| `quadClickForFeedback` | _Default:_ **false**. Setting this to true will enable rage-clicking to provide [user feedback](/v1/user-manual/time-travel/user-feedback). This option is only available if `doTimeTravel` is set to true. |
| `id` | The id you want to give to this user. Typically, you would set this to the id that you use for the user in your own system. |
| `email` | The primary email for this user. If an email is provided, but an id is not, the email will be used as the user's id. If neither are provided, the user will be treated as an anonymous visitor. |
| `hmac` | The hash-based message authentication code (HMAC) of the id (or the email if no id is provided), using your API key to sign it. See our [Secure user authentication](https://pavior.help.guide/v1/user-manual/live-chat/secure-user-authentication) article for more info. If an id (or email) is provided, but an hmac is not, the user will be treated as an **identified, but unauthenticated user**. TODO: describe signup vs lead. |
| `name` | Your user's name, if you know it. For example, if the user provided their name when signing up to your website, you can provide it here. It will be visible when you are chatting to that user in Pavior, or when you visit their profile page. |
| `customAttributes` | This is a dictionary of custom attributes and their values. Custom attributes must start with a letter and can only contain letters, numbers, and underscores. Attributes that end with `At`, `_at`, `On`, or `_on` must always be dates. See our [Custom attributes](https://pavior.help.guide/v1/user-manual/crm/custom-attributes) article for more info. |
| `shareAuth` | Set this to your primary authentication domain to "borrow" the authentication from that domain. This is useful when you want to share the Pavior session across multiple different domains. See our [Secure user authentication](https://pavior.help.guide/v1/user-manual/live-chat/secure-user-authentication) article for more details. TODO: describe primary authentication domain. |
```
Pavior('init', {
teamId: 'your-team-id',
doChat: true,
doTimeTravel: true,
id: 'user_ae12ba3a2',
email: 'eminem@example.com',
hmac: 'ca4e0d714668828ecce7440675f0e520163747de2654cf74a53ca14b9db59832',
name: 'Marshall Mathers',
customAttributes: {
industry: 'music',
isAffiliate: 1,
lastPerformanceAt: '2011-10-05T14:48:00.000Z',
}
});
Pavior('init', {
teamId: 'your-team-id',
doChat: true,
doTimeTravel: true,
shareAuth: 'auth.example.com',
});
```
---
### update
The `update` call can be used to amend some of the options, such as user attributes, that were set during `init`, without reloading the page.
The `update` call has the following options:
| `doChat` | _Default:_ **unchanged**. Setting this to true will show the chat bubble and enable full chat functionality. Setting it to false will hide the chat bubble and disable all chat functionality. |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `doTimeTravel` | _Default:_ **unchanged**. Setting this to true will enable time travel and other tracking features such as being able to add events for the user. Setting this to false will not record any part of the session, and will not allow submitting custom events for the user. |
| `id` | The id you want to give to this user. Typically, you would set this to the id that you use for the user in your own system. |
| `email` | The primary email for this user. If an email is provided, but an id is not, the email will be used as the user's id. If neither are provided, the user will be treated as an anonymous visitor. |
| `hmac` | The hash-based message authentication code (HMAC) of the id (or the email if no id is provided), using your API key to sign it. See our [Secure user authentication](https://pavior.help.guide/v1/user-manual/live-chat/secure-user-authentication) article for more info. If an id (or email) is provided, but an hmac is not, the user will be treated as an **identified, but unauthenticated user**. TODO: describe signup vs lead. |
| `name` | Your user's name, if you know it. For example, if the user provided their name when signing up to your website, you can provide it here. It will be visible when you are chatting to that user in Pavior, or when you visit their profile page. |
| `customAttributes` | This is a dictionary of custom attributes and their values. Custom attributes must start with a letter and can only contain letters, numbers, and underscores. Attributes that end with `At`, `_at`, `On`, or `_on` must always be dates. See our [Custom attributes](https://pavior.help.guide/v1/user-manual/crm/custom-attributes) article for more info. |
If you provide a different `id` (or `email` if no `id` was provided), from the `init` call, Pavior will treat this as a new session for a different user. If you previously provided an `id` in the `init` call, you can provide `null` in this call to start a new session as an anonymous visitor. This might be useful in cases such as a single-page application, where the login/logout process does not cause the page to refresh.
```
Pavior('update', {
doChat: false,
email: 'someemail@test.ca',
name: 'Some Name',
customAttributes: {
hasVisitedStore: 1
}
});
```
---
### position
The `position` command is used to reposition the chat bubble (if available). The method takes a single object as its argument, which accepts `top`, `left`, `right` and `bottom` keys, with an integer represented the fixed distance from the given side of the window to the perimeter of the chat bubble.
_Note:_ only non-zero values are accepted.
```
MomentCRM('position', {top: 50, left: 50});
```
---
### inboundMessage
Pavior's `inboundMessage` function allows you to send a message from the visitor currently on your website to your team. This command takes an object with a single key-value pair with `message` as the key and the message to be sent as the value.
It is useful for implementing alternative ways to contact support. For example, if you want your team to receive a templated message from the user when they click a button in your app.
```
Pavior('inboundMessage', {
message: 'I'm having problems with the pricing page!'
});
```
---
### open
This will open the chat view, the same as if a user clicked on the chat bubble while the chat view was closed.
```
MomentCRM('open');
```
---
### close
This will close the chat view, the same as if the user clicked the chat bubble while the chat view was open.
```
Pavior('close');
```
---
### hide
The `hide` command allows you to hide the Pavior chat bubble. This is useful in cases where you want to make sure that it is not blocking anything in the screen.
_Note:_ it is also possible to change the chat bubble's position using the [position command](https://app.pavior.com/team/pavior/helpcenter/api-reference/client-api-commands/position), and users may also move it by dragging it across the screen.
```
Pavior('hide');
```
---
### show
The `show` command allows you to make the chat bubble visible after it has been hidden using the [`hide` command](https://app.pavior.com/team/pavior/helpcenter/api-reference/client-api-commands/hide).
```
Pavior('show');
```
---
### on
Event listeners may be added to MomentCRM using the `on` command. This command takes two arguments:
1. `eventType` (required) - The id of the event type to listen for. This can be one of the following:
1. `userUpdate` - Fired whenever there is any new information to be known about the current user on the page. This will always fire at least once per page load, and any time any of their attributes are updated, either by API call or manually by one of your team members.
1. `callback` (required) - A function that will be invoked once the event is fired. Depending on the event type, the callback will have different arguments passed to it:
1. `userUpdate` - The only argument will be the user object. TODO: describe the user object
```
MomentCRM('on', 'userUpdate', (user) => {
if (user.name === 'Ben') {
alert('Hello Ben!');
}
});
```
---
### off
Event listeners defined using the [`on` command ](https://app.pavior.com/helpcenter/pavior/api-reference/client-api-commands/on)may be removed using Pavior's `off` command. It takes the same arguments as `on`.
_Note:_ the exact same instance of the callback previously passed to `on` must be passed to the `off` command in order to correctly remove it.
```
Pavior(
'off',
'userVisitedStore',
handleUserVisitedStore
);
```
---
### track
The track command allows you to turn tracking on and off. Most commonly, it is used to turn tracking on at some point after having initialized Pavior with tracking turned off. It takes an options argument, which accepts two different key-value pairs:
- `doTracking`: determines whether to turn tracking on or off. (`boolean`)
- `isTop`: should be set to `true` when the method is called from the main frame. Otherwise, it should be set to `false`. (`boolean`)
```
Pavior('track', {doTracking: true, isTop: true});
```
---
### event
The `event` command allows you to record custom events for your users. It takes two arguments:
1. `name`: the name used to identify this type of event. (`string`)
1. `data`: an object of any additional data you may want to store as part of the event. (`object`).
Upon creation of a new event type (as defined by its `name`), three attributes are automatically generated for your users:
1. ` count`: the number of times a given event has been recorded for a user.
1. ` first`: the date of the first time a given event was recorded for a user.
1. ` last`: the date of the last time a given event was recorded for a user.
These attributes may be used when applying [filters](https://app.pavior.com/team/pavior/helpcenter/user-manual/crm/filters) your users. Additionally, custom events will be displayed on your users' [history page](https://app.pavior.com/team/pavior/helpcenter/user-manual/crm/user-history). The events `data` will also be shown there.
```
Pavior('event', 'itemAddedToCart', {
itemId: 'someId'
});
```
---
### feedback
The `feedback` command is used to trigger the user feedback box (similar to what rage-clicking does if `rageClickForFeedback` is set to `true` in [init](/v1/api-reference/client-api-commands/init).
The method takes a single object as its argument, which is always the fixed string `'saved_moment'`.
See [User feedback](/v1/user-manual/time-travel/user-feedback) for more info.
```
Pavior('feedback', 'saved_moment')
```
---
## Server API
### Introduction
The Pavior server API enables you to programatically manage objects within your team, such as creating users or responding to conversations. It can (and should) be used from a server you trust.
**Never call these endpoints from a browser, because they require your api key, which any visitor to your site can then steal. Use our client API instead.** The server API is more powerful than the client API. If you need to call it from a webpage, do not call it directly. Instead, make an authenticated call to your server, and have the server call our API. This way, your API key is never revealed to the user.
The API is designed around REST. It aims to have predictable URL endpoints and uses HTTP verbs wherever possible.
---
### Authentication
Each request must include your API key for authentication. You can find your API key by going to  > Settings > Integrations > API Key.
---
### Requests
`GET` requests must be [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding)
`POST` requests must have a JSON-encoded body and the `Content-Type: application/json` header.
You must also include an `Authorization` header with your API key.
All requests must be made over HTTPS to `api.pavior.com`. Any HTTP requests are responded to with HTTP 302 to the equivalent HTTPS address.
If you are using the curl examples, make sure that any data you replace is properly shell-escaped.
```
curl -vvv -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
...
```
---
### Responses
Unless explicitly mentioned, our API will return:
- an HTTP 200 with JSON in case of success, and
- standard HTTP error codes in case of failure
---
## Server API commands
### Add a user
`POST /v1/user`
This endpoint will add a user to Pavior, to either the Leads universe or the Signups universe.
If the user identified by the id or email does not exist yet, they will be created. Otherwise, their attributes and custom attributes will be updated.
### Parameters:
- `id` (optional) - If your user has an id in your own system, set this field to the user's id. At least one of `id` or `email` is required. If an id is not provided, the email will be used as the user's id.
- `email` (optional) - The email of the user. At least one of `id` or `email` is required.
- any [built-in attribute](/v1/user-manual/crm/custom-attributes) (optional) - Will set that attribute on the user object. If `signedUpOn` is set, the user will be in the Signups universe. Otherwise, the user will be in the Leads universe. The user can be moved to a different universe later by modifying the `signedUpOn` attribute.
- `customAttributes` (optional) - A dictionary of custom attributes, to be created or updated for the user. Custom attributes that end with `At`, `_at`, `On`, or `_on` must always be dates. See our [Custom attributes](https://pavior.help.guide/v1/user-manual/crm/custom-attributes) article for more info. When rendered on the website, the custom attribute will split the name of the attribute based on snake case or camel case. For example, `snake_case` will be rendered `Snake Case` and `camelCase` will be rendered `Camel Case`.
### **Return:**
The endpoint will return `{"data":true}` if successful, and a standard HTTP error code otherwise.
```
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"id": "unique-user-id",
"email": "user@example.com",
"name": "John Doe",
"signedUpOn": "2021-07-16T18:30:40.712587+00:00"
}' \
https://api.pavior.com/v1/user
```
---
### Send an outbound message
`POST /v1/outbound_message`
This endpoint will start a new conversation with one of your users. It is equivalent to starting a new conversation with the user from their profile page. If any integrations are set up, they will fire just as they would when one of your team members manually initiates a conversation.
### Parameters:
- `id` (optional) - If you identify your users with ids from your own system, set this field to the user's id. At least one of `id` or `email` is required. If an id is not provided, the email will be used as the user's id.
- `email` (optional) - The email of the user. At least one of `id` or `email` is required. If an email is not provided, and the user does not have an email set, they will only be able to see the message in their chat bubble, email transcripts will not be sent. **If an** `id` **is provided, this field will be completely ignored. The message will be sent to the email of the user.**
- `subject` (required) - The subject of the message. This will only appear in the email transcript, and will not be shown in the user's chat bubble.
- `message` (required) - The message that you want to send.
- `senderId` (required) - The id or email of the team member or team inbox to send the email from.
- `senderProfileId` (optional) - The sender profile id that you'd like to send from, if the `senderId` has set up multiple sender profiles. If omitted, the team member's default sender profile will be used.
### **Return:**
The endpoint will return `{"data":true}` if successful, and a standard HTTP error code otherwise.
```
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"id": "unique-user-id",
"subject": "You are awesome!",
"message": "Doing great!\nKeep it up!",
"senderId": "teammate@company.com"
}' \
https://api..com/v1/outbound_message
```
---
### Send an inbound message
`POST /v1/inbound_message`
This endpoint will start a new conversation with your team, from one of your users. It is equivalent to the user opening the chat bubble and starting a new conversation.
**This endpoint is authenticated, so the user will only be able to see it in their chat bubble if they have been authenticated.** Learn more about client authentication. An email transcript will still be sent if someone on your team responds.
### Parameters:
- `id` (optional) - If you identify your users with ids from your own system, set this field to the user's id. At least one of `id` or `email` is required. If an id is not provided, the email will be used as the user's id.
- `email` (optional) - The email of the user. At least one of `id` or `email` is required. If an email is not provided, and the user does not have an email set, they will only be able to see the message in their chat bubble, email transcripts will not be sent. If both an id and an email are provided, the user's email will be set or updated to the new email.
- `subject` (required) - The subject of the message. This will only appear in the email transcript if one of your team members responds to the message, and will not be shown in the user's chat bubble.
- `message` (required) - The message that you want to send.
- `assignedToId` (optional) - The id or email of the team member or team inbox to send the email from. If not assigned, the message will go through any assignment rules you've set up, which default to putting everything in the Unassigned inbox.
### **Return:**
The endpoint will return `{"data":true}` if successful, and a standard HTTP error code otherwise.
```
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"id": "unique-user-id",
"subject": "You are awesome",
"message": "Doing great!\nKeep it up!"
}' \
https://api.pavior.com/v1/inbound_message
```
---
### Add an event
`POST /v1/events`
This endpoint will generate an event for the target user. The event will show up on the user's History tab in their profile.
### Parameters:
- `id` (optional) - If you identify your users with ids from your own system, set this field to the user's id. At least one of `id` or `email` is required. If an id is not provided, the email will be used as the user's id.
- `email` (optional) - The email of the user. At least one of `id` or `email` is required.
- `events` (required) - A list of events to add for that user. Each event has the following fields:
- `eventType` (required) - An id that can be used to identify events of a similar nature. For example, you might use a `createdProject` event type if one of the actions in your app is to create a project.
- `createdAt` (optional) - The date that the event happened. If omitted, it will default to the current time.
- `metaJson` (optional) - An object containing any extra details about the event. For example, you might set this to `{"projectStart": "blank"}` if your user started their project from a blank template.
### **Return:**
The endpoint will return `{"success":"success","num_events": X}` if successful, where `X` is the number of events added. It will return a standard HTTP error code otherwise.
```
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"id": "unique-user-id",
"events": [{
"eventType": "createdProject",
"metaJson": {
"projectStart": "blank",
"imported": false
}
}]
}' \
https://api.pavior.com/v1/events
```
---