weavix REST APIs allow admins to perform certain actions in an automated fashion from outside the weavix system. In order to do this, you must have a valid API key for your account.
Below you will find examples of useful weavix APIs and how they can be utilized.
Getting started
All calls use the base URL https://api.weavix.com and must include your API key in the Authorization header:
Authorization: Basic <your API key>
Content-Type: application/jsonErrors are returned with an HTTP status and a JSON body, for example:
400 { "message": "INVALID_FIELD", "details": { "field": "name", "reason": "duplicate" } }
404 { "message": "NOT_FOUND", "details": {} }
Crafts
Create a craft
Creates a new craft with the specified name and returns it, including its id.
POST https://api.weavix.com/core/crafts{
"name": "string"
}Get a list of all crafts
Returns a list of all the Crafts on your account. You can obtain the craftId for a specific Craft from this list.
GET https://api.weavix.com/core/crafts
Geofences
Get a list of all Geofences
Returns a list of all the Geofences on your account. You can then filter these down by looking at the facilityId of all the geofences to know which ones belong to your site.
GET https://api.weavix.com/track/geofences
Permission Groups
Get a list of all Permission Groups for a Site
Returns a list of all the Permission Groups on the specified Site. You can obtain the groupId for a specific Permission Group from this list. See below to find a Site ID
GET https://api.weavix.com/core/groups/{facilityId}
Sites
Get a list of all Sites
Returns a list of all the Sites on your account. You can obtain the facilityID for a specific Site from this list.
GET https://api.weavix.com/track/facilities
User Management
Get a list of all users on the account
Returns a list of all the Users on your account. You can obtain the userId for a specific User from this list. Each user in the list also includes their crafts, permission group, sites and properties.
GET https://api.weavix.com/core/people/namesGet a user
Gets the user profile information of the specified user, such as name, email, phone number and badges.
GET https://api.weavix.com/core/users/{id}{id} is the user id of the user you wish to view
Get a user with their properties
Gets one user together with their crafts, permission group, sites and properties (the custom key/value properties set on the user, returned as a list of { "key": "string", "value": "string" }). A user with no properties returns an empty list.
GET https://api.weavix.com/core/people/{id}{id} is the user id of the user you wish to view
To get the properties of every user at once, request the full list. Use limit and offset to page through large accounts:
GET https://api.weavix.com/core/people?limit=100&offset=0This call returns every user and cannot filter by property. To find the user with a particular property value, read the list and match on properties in your own code.
Delete a user
Deletes the specified user from your account.
DELETE https://api.weavix.com/core/people/{id}{id} is the user id of the user you wish to delete
Add a user
Creates a new user on your account with all the provided information. This user will be created, but will still need to be Activated after creation.
POST https://api.weavix.com/core/people/new-user{
"folderId": "string",
"firstName": "string",
"lastName": "string",
"email": "string",
"phone": "string",
"group": "string",
"facilities": [
{
"facilityId": "string",
"facilityGroup": "string"
}
],
"crafts": [
"string"
],
"locale": "en"
}Required fields are firstName, lastName, group, and facilities (if not a global-admin).
Folders
If you’ve created folders for your users in weavix, you can specify which folder a user should be created in. The folderId is the unique identifier for that folder and can be determined by opening that folder in weavix and locating the folderId in the URL.
Permissions
Global Admin: group
Options for group are “global-admin” or “none” depending on if the user should be a Global Admin or not, respectively.
Site Permission: facilityGroup (a unique identifier for one of your permission groups)
The facilityGroup should be the id of one of your Permission Groups (can be determined by requesting a list of Permission Groups)
Sites
Site: facilityId (the unique identifier for your site)
FacilityId can be determined by requesting a list of facilities
Crafts
Multiple crafts can be assigned to a user
Crafts: (a unique identifier for one of the crafts you have created in weavix)
Locale
The locale allows you to specify the default language for the user on their weavix devices.
This must be two digit ISO 639 language code for one of the weavix supported languages. If not provided, users will be set to English ("locale": "en") by default.
The response is the new user, including their id and userId.
Update a user
Updates an existing user on your account with all the provided information. Only updates with the keys provided, so you can choose to update just a single piece of information if you wish.
PUT https://api.weavix.com/core/people/{id}{
"folderId": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"group": "string",
"crafts": [
"string"
],
"locale": "en"
}{id} is the user id of the user you wish to edit.
See the above information regarding adding a user for explanations of each key. This call updates a user’s profile information. This call does not change a user’s sites or permission groups.
Send a message to a channel
Get a list of all Admin Defined Channels
Returns a list of all the Admin Defined Channels on your account. You can obtain the channelId for a specific channel from this list.
GET https://api.weavix.com/core/channels
Send a message to an Admin Defined Channel
Allows you to send a message to a specific channel that will show to a user as a System Message. Messages sent this way are text only.
POST https://api.weavix.com/api/{channelId}/message{
"message": "string",
"senderName": "string",
"readAloud": true
}Requires the {channelId} for the channel you wish to send a message to.
Body:
message field is the message you wish to send to the channel and is required.
senderName is the name you wish to be displayed as the sender of the message. This field is optional and if you choose to not pass in a senderName, the message will appear to be sent from "weavix Integrations".
readAloud is set to true if you want the message to be read out loud when received on a walt. If you set this to false, the message will follow the user's settings when deciding whether to read it out loud or not.
Example of sending a message to a channel:
{
"message": "Line 1 press is down. Low pressure warning.",
"senderName": "Line 1 Press",
"readAloud": true
}
Get the messages from a channel
Allows you to get all of the messages that have been sent to a channel with the provided parameters. The response is an object with a messages list.
POST https://api.weavix.com/external/channels/{channelId}/messages/search{
"fromDate": "yyyy-mm-ddThh:mm:ssZ",
"toDate": "yyyy-mm-ddThh:mm:ssZ",
"contentTypes": [
"audio"
],
"pageSize": 100,
"next": "string"
}Body:
fromDate field is the timestamp of the beginning of the timeframe you want to pull messages for. The timestamp format is "yyyy-mm-ddThh:mm:ssZ" with the time being UTC.
toDate field is the timestamp of the end of the timeframe you want to pull messages for. The timestamp format is "yyyy-mm-ddThh:mm:ssZ" with the time being UTC.
contentTypes specifies all the types of message you want to pull. Types include:
audio: Push-to-Talk messages
image: Picture messages
video: Video Messages
file: Attached files sent from Web Radio or the weavix Mobile App
link: a message that is simply a link to a web page
pageSize field specifies how many messages you would like to be included in the response. This field is optional and has a default and maximum value of 1000.
next field is optional and is used if there are more messages available than the specified pageSize. If this is the case, you will receive a "next" value at the end of your initial response. You can pass this value in on your next call to get the "second page" of results. Repeat this process to iterate through all "pages" of messages available.
Send a message to an individual user
Get a list of all users on the account
Send a message to a user
Allows you to send a message to a specific user. You can specify a "Sender Name" and the message will show as a message from the specified sender.
POST https://api.weavix.com/api/admin/channel-message{
"userId": "string",
"channelName": "string",
"message": "string",
"senderName": "string",
"messageLanguage": "en-US",
"readAloud": true,
"mediaUrl": "string",
"channelImageUrl": "string",
"responseUrl": "string"
}Body:
userId field is the ID of the user you wish to send the message to and is required
channelName field is the name of the channel you will create with the user and is required. Sending again to the same user with the same channelName continues the same conversation; a new channelName starts a new one.
message field is the message you wish to send to the channel and is required
senderName is the name you wish to be displayed as the sender of the message and is required.
messageLanguage field specifies the language of the message you are sending. Use a language and region code such as "en-US" or "es-MX" (see the list below). A two letter code such as "en" is rejected with an error. If not provided, the message is treated as English ("en-US").
readAloud is set to true if you want the message to be read out loud when received on a walt. If you set this to false, the message will follow the user's settings when deciding whether to read it out loud or not.
mediaUrl field is optional. It is the web address of a picture (PNG, JPEG or GIF) or video (MP4) to include with your message. The address must be reachable from the internet, must not redirect, and must respond within 10 seconds. If the file cannot be retrieved, the whole message is rejected.
channelImageUrl field is optional. This field allows you to provide an image that will be used as the "profile avatar" for the message, with the same requirements as mediaUrl.
responseUrl field is optional. It must be an https address. If a URL is provided in this field, when the user replies in this channel, weavix sends the reply to this URL as an HTTP POST with a JSON body. Any query string you include on the URL is kept. The call has a 20 second limit and is not retried.
Example of what weavix sends to your responseUrl:
{
"message": "text of the reply, or the transcript of a push-to-talk",
"senderName": "string",
"userId": "string",
"messageLanguage": "en-US",
"attachments": [ { "type": "audio", "file": { "uri": "string" }, "duration": 3 } ],
"channel": "the channelName you sent"
}Supported messageLanguage values
English: en-US
Spanish: es-MX, es-AR, es-BO, es-CL, es-CO, es-CR, es-CU, es-DO, es-EC, es-ES, es-GQ, es-GT, es-HN, es-NI, es-PA, es-PE, es-PR, es-PY, es-SV, es-US, es-UY, es-VE
Portuguese: pt-BR
German: de-DE
Italian: it-IT
French: fr-FR
Dutch: nl-NL, nl-BE
Arabic: ar-AE, ar-BH, ar-DZ, ar-EG, ar-IQ, ar-JO, ar-KW, ar-LB, ar-LY, ar-MA, ar-OM, ar-QA, ar-SA, ar-SY, ar-TN, ar-YE
Swahili: sw-KE, sw-TZ
Other: am-ET, fa-IR, fil-PH, hi-IN, ja-JP, km-KH, ko-KR, lo-LA, ms-MY, my-MM, ne-NP, ps-AF, ru-RU, sq-AL, th-TH, uk-UA, vi-VN, zh-CN
Forms
Create a form
Allows you to create a new form. Forms are created as an empty shell first. The response returns the generated id, which is then used to add questions with the Update a form call.
POST https://api.weavix.com/core/forms{
"id": null,
"name": "string",
"acceptingResponses": true,
"facilityIds": [
"string"
],
"folderId": null,
"tags": [],
"whoCanSubmit": {
"conditions": {
"conditions": [],
"type": "and"
},
"advancedCondition": {
"conditions": [],
"type": "and",
"enabled": false
}
},
"questions": [],
"currentVersion": 1,
"conditions": {
"conditions": [],
"type": "and"
}
}Body:
id must be sent as null on creation. The service generates the form ID and returns it in the response.
name is the display name of the form. Form names must be unique; creating a form with a name that is already in use returns an error.
acceptingResponses controls whether the form is open for submissions. If set to false, the form is saved but users will not be able to submit it.
facilityIds is an array of the sites the form should be available at. At least one site must be provided.
folderId field is optional. It is the ID of the folder you wish to place the form in. Send null to leave the form at the root level.
tags field is optional. It is an array of tags used to categorize the form.
whoCanSubmit defines which users are permitted to submit the form. Send empty conditions arrays to make the form available to all users at the selected sites.
questions should be sent as an empty array on creation. Questions are added using the Update a form call.
currentVersion is the version number of the form and should be set to 1 on creation.
conditions field is optional and reserved for form-level display logic. Send empty conditions arrays when not in use.
Response:
{
"id": "string",
"facilityIds": [
"string"
],
"name": "string",
"acceptingResponses": true,
"tags": [],
"questions": [],
"currentVersion": 1,
"whoCanSubmit": { ... }
}id is the generated form ID. This value is required for the Update a form call.
Update a form
Allows you to update an existing form, including adding, editing, or removing its questions.
PUT https://api.weavix.com/core/forms/{formId}/{version}{
"id": "string",
"name": "string",
"acceptingResponses": true,
"facilityIds": [
"string"
],
"folderId": null,
"tags": [],
"whoCanSubmit": {
"conditions": {
"conditions": [],
"type": "and"
},
"advancedCondition": {
"conditions": [],
"type": "and",
"enabled": false
}
},
"questions": [
{
"qId": "string",
"question": "string",
"type": "dropdown",
"details": {
"type": "dropdown",
"required": false,
"options": [
{
"value": "string",
"display": "string"
}
]
},
"required": false
}
],
"currentVersion": 1,
"conditions": {
"conditions": [],
"type": "and"
}
}URL:
formId is the ID of the form returned by the Create a form call.
version is the version of the form you are updating. A new form is version 1; a call to GET https://api.weavix.com/core/forms lists the versions of each form. A version that does not exist returns a 404 error.
Body:
Send the complete form object on every update, not only the fields being changed. Leaving fields out of the body, such as questions, can cause the request to fail with an error. id in the body must match the formId in the URL. currentVersion is saved exactly as you send it, so send the form’s existing version number (1 for a new form).
questions is an array of the questions on the form. The order of the array is the order the questions are presented to the user. To remove a question, omit it from the array.
qId is the unique identifier of the question and must be a GUID. Supply a new GUID when adding a question, and reuse the existing qId when editing a question so that previously collected responses stay associated with it.
question is the text of the question as presented to the user. This text is translated into the user’s set language.
type is the question type, for example dropdown.
details holds the configuration for the question. The type inside details must match the question’s type.
details.required controls whether the user must answer the question before submitting the form.
details.options is the array of selectable answers, and applies to question types that present a list of choices. value is the value stored with the response and display is the text shown to the user. The display text is translated into the user’s set language.
required is also set at the question level and should be sent with the same value as details.required.
Response:
The response returns the saved form.
{
"id": "string",
"facilityIds": [
"string"
],
"name": "string",
"acceptingResponses": true,
"tags": [],
"folderId": null,
"questions": [ ... ],
"currentVersion": 1,
"whoCanSubmit": { ... }
}Get results from a specific form
Allows you to pull all of the submissions for a specific form. Each submission includes the form (its id, version and name), the person who submitted it (completed.personId and completed.personName), the date it was completed (completed.date), their answers (completed.answers, each with a qId and an answer), and the submission id. The personId can be used with the Get a user with their properties call above to look up more about that person.
GET https://api.weavix.com/v1/core/forms/{formId}/submissions
Requires the formId to be included. This formId can be found by opening the Form in the weavix Console and locating the ID at the end of the URL.
Get a single form submission
Allows you to pull one submission by its ID, instead of every submission for the form. This is useful when a workflow or integration is given the ID of a submission that was just completed and needs only that one. The ID is the id of each item returned by the Get results from a specific form call.
GET https://api.weavix.com/v1/core/forms/submissions/{submissionId}Requires the submissionId to be included. The response is a single submission with the same fields as an item in the results list: the form (id, version and name), completed (personId, personName, date and answers), and the submission id.
Mass Alerts
Get the types of alerts available
Allows you to pull a list of all the available alert types. You will need the ID of the alert type you want to trigger or pull information about.
GET https://api.weavix.com/core/alert-types
Send a Mass Alert
Allows you to send out a Mass Alert for a facility.
POST https://api.weavix.com/track/facility-alerts/{facilityId}{
"alertTypeId": "string",
"crafts": [
"string"
],
"message": "string",
"location": {
"currentlyIn": true,
"start": "yyyy-mm-ddThh:mm:ssZ",
"end": "yyyy-mm-ddThh:mm:ssZ",
"facilityIds": [
"string"
],
"geofenceIds": [
"string"
]
}
}Body:
alertTypeId field is the ID of the Alert Type you wish to invoke
crafts field is an array of any crafts you would like to target in the alert. The crafts field is optional. If crafts are specified, a user will only receive this alert if they belong to one of the select crafts.
message is the text you wish to send in the alert. For walts, this text will be read out loud to the user and the message will be translated into the user's set language.
location field is optional and controls who receives the alert based on where they are.
Leave out location to send the alert to everyone assigned to the site (narrowed by crafts if provided), whether or not they are on site right now.
Include location to send only to people who are on site. Provide facilityIds (the site ID again) to use on-site status, and/or geofenceIds to limit to certain geofences. If location has neither facilityIds nor geofenceIds, nobody receives the alert.
currentlyIn field:
true: the alert is sent only to people who are on site at the selected site (or in the selected geofences) right now. start and end are not needed.
false (or left out): the alert is sent only to people who were on site at any time between start and end. Both start and end are required; without them nobody receives the alert. People who were never on site in that time period do not receive it.
start and end fields use the timestamp format "yyyy-mm-ddThh:mm:ssZ" with the time being UTC.
geofenceIds field is optional. It is an array of geofences you wish to target for the alert. If geofences are specified, only users who are reporting locations in one of these geofences will be sent an alert.
Response: the alert that was created, plus a people list containing the ID of everyone it was sent to. If people is empty, nobody received the alert and it is not recorded in the alert history.
Get history of all alerts at a site
Allows you to pull a list of the alerts sent for the specified site. Returns the 1,000 most recent alerts. The list does not show who received each alert. A facilityId that does not exist returns a 400 error.
GET https://api.weavix.com/track/facility-alerts/{facilityId}
Comments
0 comments
Please sign in to leave a comment.