Getting started
Welcome to the Pavior API reference. Our API is broken up into two parts:
To the right, you will find relevant code examples for each section.
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
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 <head> 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
The init call is required to be called before you can use any Pavior functionality on your website. It is used to:
The init call has the following options:
| Required. You must set this to your team id. |
| 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. |
| 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. |
| Default: false. Setting this to true will enable rage-clicking to provide user feedback. This option is only available if |
| 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. |
| 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. |
| 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 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. |
| 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. |
| 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 |
| 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 article for more details. TODO: describe primary authentication domain. |
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:
| 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. |
| 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. |
| 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. |
| 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. |
| 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 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. |
| 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. |
| 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 |
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.
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.
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.
This will open the chat view, the same as if a user clicked on the chat bubble while the chat view was closed.
This will close the chat view, the same as if the user clicked the chat bubble while the chat view was open.
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, and users may also move it by dragging it across the screen.
The show command allows you to make the chat bubble visible after it has been hidden using the hide command.
Event listeners may be added to MomentCRM using the on command. This command takes two arguments:
eventType (required) - The id of the event type to listen for. This can be one of the following: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.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:userUpdate - The only argument will be the user object. TODO: describe the user objectEvent listeners defined using the on command 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.
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)The event command allows you to record custom events for your users. It takes two arguments:
name: the name used to identify this type of event. (string)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:
<name> count: the number of times a given event has been recorded for a user.<name> first: the date of the first time a given event was recorded for a user.<name> last: the date of the last time a given event was recorded for a user.These attributes may be used when applying filters your users. Additionally, custom events will be displayed on your users' history page. The events data will also be shown there.
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.
The method takes a single object as its argument, which is always the fixed string 'saved_moment'.
See User feedback for more info.
Server API
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.
Each request must include your API key for authentication. You can find your API key by going to 
> Settings > Integrations > API Key.
GET requests must be URL-encoded
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.
Unless explicitly mentioned, our API will return:
Server API commands
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.
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.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 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.The endpoint will return {"data":true} if successful, and a standard HTTP error code otherwise.
<br>
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.
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.The endpoint will return {"data":true} if successful, and a standard HTTP error code otherwise.
<br>
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.
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.The endpoint will return {"data":true} if successful, and a standard HTTP error code otherwise.
<br>
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.
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.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.
<br>