Wix Answers Developers Overview
The WIX Answers REST API enables you to use code to interact with the Wix Answers back-end. You can use the API to create webhooks that interact with the Wix Answers front and back-ends, or create a new front-end app that works with the Wix Answers back-end. You can also use the API to get information about your customers and their Wix Answers history.The API documentation assumes that you are familiar with Wix Answers features and have read the knowledge base articles about these features.The API documentation includes articles with the following subcategories in the Developers category:
API Overview: This document API Reference: All public Wix Answers APIs. Start with the API Reference Overview. Data Reference: Common objects and enumerations returned by APIs, as well as required permissions and roles Procedures: Frequently asked workflow questions, such as how to find information you might need or how to combine APIs or webhooks to perform common procedures SDK: How and where to create code that works with the APIs and back-end. Start with the Wix Answers SDK Overview. Webhooks: How to create webhooks that may be called from the APIsNote: Keep a Debug LogWe highly recommend that you create a minimum 3-day log of responses from Wix Answers. This will ease your debugging process in the case of any issues.You can test API calls using cURL or any similar software.Wix API methods accept HTTPS requests in JSON content-type with UTF-8 character set (application/json; charset=utf-8). Parameters are case-sensitive: for example, ID is not accepted when id is expected.Successful responses are returned by HTTPS in JSON format (application/json) with status headers that include codes in the 200-300 range. For example:Status: 200
{
"id": "bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa",
"name": "Article Title",
...
"creationDate": 1568180889000
}API EndpointAll URLs referenced in the API documentation have the following endpoint: https://<tenant_subdomain>.wixanswers.comAuthorizationSome API endpoints do not require authorization. Most endpoints require a JWT authorization token generated from an API key. The token is valid for one hour and must be sent on every request using an Authorization header:
Authorization: Bearer <token>Token TypesA user-specific authorization token has the authorization for that user or agent. This token has an intersection of the permissions of the user and the API key, and contains the user's ID. A general authorization token (not specific to a user) has all permissions of the API key and contains the user ID for "System User".
Some endpoints require a user-specific authorization token. For these endpoints, a general authorization token does not work. For example, adding a ticket as a specific user requires a user-specific token; see Add a Ticket as Authenticated User.
For all other endpoints, you can use a general token, if the API key has the required permission, or a user-specific token, if the API key + user ID has the required permission. If you use the general token, Wix Answers records the activity as done by "System User".
In some cases, such as reading articles on a public website, no authorization token is required.API Keys, Roles, and PermissionsWix Answers uses API keys, roles, and permissions to determine whether you are allowed to access an endpoint.
You can configure multiple API keys in Wix Answers, and you can enable or restrict sets of permissions for each API key.
For more information about creating API keys and selecting sets of permissions, see Obtaining an API Key to Your Wix Answers Account. For the list of which permissions are enabled or disabled with each selection, see Roles and Permissions.In addition to restricting permissions by API keys, you can assign roles to agents. Agents are users that are assigned any role: these are your team members who have access to the Wix Answers app. Roles are collections of permissions. Wix Answers comes with three out-of-the-box roles: Viewer, Agent, and Admin. Viewers have access to read-only Wix Answers endpoints and to the Wix Answers app. Agents can do anything Viewers can do, but they also can manage users, tickets, articles, calls, and other non-administrative areas of the app. An Admin(istrator) can do anything an Agent can do, and can also manage other agents and perform other administrative tasks. An admin can define other roles in the Wix Answers App.
Since a non-agent user does not have a role, a user-specific token generated for this kind of user has no permissions, not even the ones in the API key. A user-specific token generated for an agent has an intersection of the permissions of the agent's role and the API key. For example, if an agent has a role that includes FETCH_ARTICLES but does not include MANAGE_ARTICLES, then a token generated for this agent does not include MANAGE_ARTICLES, even if the API key does. This token cannot access any endpoints that require MANAGE_ARTICLES.For some endpoints, no token is required. For some endpoints, any valid token is required and the endpoint does not require any specific permission. For some endpoints, a user-specific authorization token is required but the endpoint does not require any specific permission. And for some endpoints, any valid token is required but the API key and the user associated with the token (when sending a user-specific authorization token) must all have a specific permission.
To summarize, the following lists the cases in which you can access a particular endpoint:
The endpoint does not require you to send a tokenOR
The endpoint requires you to send a token The endpoint does not require a token with a specific permission You send a valid tokenOR
The endpoint requires you to send a user-specific token You send a valid user-specific tokenOR
The endpoint requires you to send a token The endpoint requires a specific permission You send a valid token The permission related to the endpoint, if any, is
Included in the API key's list of permissions, AND Included in the role assigned to the user associated with the token, if any In a few cases, the endpoint requires you to send a user-specific token AND the endpoint requires a specific permission. In this case, the user for the token must be an agent with a role that includes the required permission and the API key must include the required permission.Help Center Authorization OverrideYou can configure your help center to require users to register before they can access any contents. In this case, all API calls require an authorization token, even if no authorization is indicated in the documentation.Tokens with no User SpecifiedIf you request a token without specifying the user that the token is for, the token is a general token with admin privileges, but will not work for endpoints that require a token associated with a specific user.Authenticated UsersTo be an authenticated user means that Wix Answers has authenticated the user's email and the user has a unique ID (GUID).Chat Unauthenticated User HeaderWhen starting a chat for an authenticated user, first request an authorization token using the user's GUID. For information about this token and about chat API endpoints, contact Wix Answers customer support.PartnersA partner is an authenticated user associated with multiple companies. Partners create and monitor tickets on behalf of customers in these companies. Partners are not agents.Requesting an Authorization Token (Without Specifying a User)Requesting an Authorization Token Must be Made as a Server-Side RequestYou send the tenant secret in order to obtain an authorization token. This secret is extremely sensitive and must be kept private. Therefore, requests to obtain an authorization token must be made from your servers as server-side requests, NOT from a client.The authorization token is also sensitive, since it enables its holder to act on behalf of the user that it represents. It is important to ensure that the token is kept secure (from everyone except the client/user who will use it). Therefore, Wix Answers recommends that all client requests be made to your servers, which in turn send the token as server-side requests to the Wix Answers API.To obtain an API token without specifying a user:
In the Wix Answers app, navigate to Settings > Tools > Webhooks & API Keys (https://<tenant_subdomain>.wixanswers.com/app/settings/tools/webhooks-and-api/webhooks) and copy Key ID (Public) and Secret (Private). Make a request to the token generator endpoint, with the parameters key and secret (both are required).
POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token
Content type: application/json; charset=utf-8 Accept: application/jsonPayload Structure:POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token
{
"keyId":"<key_id>",
"secret":"<secret>"
}Request Example Using cURL:curl -XPOST 'https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token' -d '{
"keyId":"<key_id>",
"secret":"<secret>"
}'
-H 'Content-Type: application/json; charset=utf-8'
-H 'Accept: application/json'Response Example:{
"token":"eyJlbmMiOiJBMTI0NNIiwiYWxnIjoiZGlyIn0..9-fRNeE8J3SspYg9.3eaSroE6kEIpLfdgmhg0fvOxMUs1YAHZC6dHacAkZOOjD1EA-1pApV863H1fxqCVoGbq2163PnE--83rFqU4RxbH33tTbfw0kE-baf1YEnbVt5MOWoQ_F59FzY.BiTX-Ao-OcaDeRuEDIuaeA"
}Requesting a Specific User's Authorization Token POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/tokenIf you have the required permission (users with the agent or admin roles have this permission), you can get a token for a specific user. This kind of token is required where noted in the documentation. You must have the user's GUID.Content type: application/json; charset=utf-8Accept: application/jsonPayload Structure:POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token
{
"keyId":"<key_id>",
"secret":"<secret>",
"userId":"<GUID>"
}Request Example Using cURL:curl -XPOST 'https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token' -d '{
"keyId":"<key_id>",
"secret":"<secret>",
"userId":"77bc8694-5ccf-436c-ab2b-543563a5f425"
}'
-H 'Content-Type: application/json; charset=utf-8'
-H 'Accept: application/json'Response Example:{
"token":"eyJlbmMiOiJBMTI0NNIiwiYWxnIjoiZGlyIn0..9-fRNeE8J3SspYg9.3eaSroE6kEIpLfdgmhg0fvOxMUs1YAHZC6dHacAkZOOjD1EA-1pApV863H1fxqCVoGbq2163PnE--83rFqU4RxbH33tTbfw0kE-baf1YEnbVt5MOWoQ_F59FzY.BiTX-Ao-OcaDeRuEDIuaeA"
}Requesting a Specific User's Authorization Token from a Widget POST https://<tenant_subdomain>.wixanswers.com/api/v1/widgets/{widget GUID}/authIf you have the required permission (users with the agent or admin roles have this permission), you can get a token for a specific user from a widget using the user's email address. If the user is not registered as authenticated in Wix Answers, Wix Answers registers the user as authenticated before returning the token.This is a shorter process than adding the user, receiving the user's GUID, and then requesting a token using the GUID.Content type: application/json; charset=utf-8Accept: application/jsonPayload Structure:POST https://<tenant_subdomain>.wixanswers.com/api/v1/widgets/{widget GUID}/auth
{
"email":"<email_address>",
"keyId":"<key_id>",
"secret":"<secret>",
"externalId":"<external_SSO_ID>",// String. If provided, and the tenant
// uses SSO, then this value is used
// to identify the user, instead of
// the email address.
// If Wix Answers registers this user as an authenticated user,
// it will add the following optional parameters to the user record.
// If the tenant uses SSO, it will also add the email address (above).
// If the user is already registered, these parameters are ignored.
"firstName":"<first_name>", // If not provided, the username
// of the email address is used.
"lastName":"<last_name>"
}Request Example Using cURL:curl -XPOST 'POST https://<tenant_subdomain>.wixanswers.com/api/v1/widgets/77bc8694-5ccf-436c-ab2b-543563a5f425/auth' -d '{
"keyId":"<key_id>",
"secret":"<secret>",
"email":"user@yourdomain.com"
}'
-H 'Content-Type: application/json; charset=utf-8'
-H 'Accept: application/json'Response Example:{
"token":"eyJlbmMiOiJBMTI0NNIiwiYWxnIjoiZGlyIn0..9-fRNeE8J3SspYg9.3eaSroE6kEIpLfdgmhg0fvOxMUs1YAHZC6dHacAkZOOjD1EA-1pApV863H1fxqCVoGbq2163PnE--83rFqU4RxbH33tTbfw0kE-baf1YEnbVt5MOWoQ_F59FzY.BiTX-Ao-OcaDeRuEDIuaeA"
}Important Information about Updating Structures Using the APIFields in a PUT request entirely replace the fields in the Wix Answers back-end. Unless noted, you cannot append information to an existing field.To modify the existing contents of a field:Get the structure using the relevant GET request.Extract the relevant field.Modify the field as required.PUT the modified field back to Wix Answers.Common Elements in API Payloads / ObjectsThe following formats or values repeatedly appear in the requests you make to, or in the structures returned by, Wix Answers.Note About Undocumented ParametersMost return structures include additional parameters not documented in this guide. These parameters are irrelevant and can be safely ignored.Global IDs (GUID)Many records, such as users, tickets, labels, and so forth, are uniquely identified by a global ID, also known as a GUID. A GUID looks something like e932c0a3-6e9b-43cf-b3a9-90f6ee6a5b07.Unix Time StringsUnix time strings are integers indicating the number of seconds since Jan 1, 1970 00:00:00. For example, 1605020237. Unix time strings are commonly used to indicate the creation or last modified time of a record.Date StringsDate strings, such as those used in request payloads, are in the format yyyy-MM-dd'T'HH:mm:ss. For example, 2012-07-09T19:22:09.Languages / LocalesClick here to see the list of supported languages.Import IDDuring the Wix Answers on-boarding process, Wix Answers can help you load your initial data by importing users, companies, articles, categories, tickets, and replies. These items are tagged during the import process with an import ID (importId).You can use your own code (such as in a webhook) to filter these items based on their import ID.API Request Rate LimitThe Wix Answers APIs have a rate limit. We reserve the right to adjust the rate limit for given endpoints so we can provide a high quality of service for all clients. If you need to make more requests than the limit, please contact us and we will try to accommodate your request.API Usage Legal NoticeYour use and access to the API are expressly conditioned on your compliance with the policies, restrictions, and other provisions related to the API set forth in our Terms of Use and our Privacy Policy. If we believe that you have or attempted to violate any term, condition, or the spirit of these policies or agreements, your right to access and use the API may be temporarily or permanently revoked.
