Wix Answers API 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, as well as common objects and enumerations returned by APIs. Start with the API Reference Overview. 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. The token is valid for one hour and must be sent on every request using an Authorization header:Authorization: Bearer <token>App Settings, Roles, and PermissionsWix Answers uses app settings, roles, and permissions to determine whether you are allowed to access an endpoint.
You can configure app settings to restrict access to specific endpoints. The token retrieved by an app with these settings cannot access these endpoints, regardless of your role/permissions.
Any user can access some endpoints without any permissions. However, see Token Types, below. For all other endpoints, a user must be an agent with a specific role. An agent is a user that is assigned any role.
Roles are collections of permissions. Wix Answers comes with three out-of-the-box roles: Viewer, Agent, and Admin. Viewers have read-only access to Wix Answers endpoints and 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.
You can access any endpoints that are enabled for any permissions of your role, as long as these permissions are also enabled by the app settings. In addition, some endpoints simply require you to be an agent; you can access these endpoints as long as you are an agent, with any role.
For more information, see Roles and Permissions.Token TypesA user-specific authorization token has the authorization for that user. This token not only has the permissions of the user, it also contains the user's ID. A general authorization token (not specific to a user) has all of the permissions enabled by the app settings, but does not contain a user ID.Some endpoints require a user-specific authorization token. For these endpoints, a general authorization token does not work, even though the general token has the required permissions. 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 or a user-specific token with the required permissions. If you use the general token, Wix Answers records the activity as done by the default admin user for your tenant, which appears as "System User" in the Wix Answers UI.In some cases, such as reading articles on a public website, no authorization token is required.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 calling a chat API without an authenticated user token, you must add an additional header to the API request. For more information, see Chat Unauthenticated User Header in the Chats API page.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 > 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/tokenContent type: application/json; charset=utf-8Accept: 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. Unix time strings are commonly used to indicate the creation or last modified time of a record.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.
