Who can use this feature?
System administrator
Plan Type: Enterprise
Difficulty: Medium
Qwil Messenger offers 15 master APIs enabling Enterprise customers to perform chat and contact functions ranging from sending a simple message on someone's behalf to getting your contact list. Actions performed by APIs follow the same rules as conventionally using Qwil, but allow greater freedom for automation and integration.
This guide will help you develop programmes to automate your organisations messaging using the following API calls. You can also view all our APIs by accessing our Postman collection.
You will need to provide certain permissions for your keys to perform certain functions. These are outlined with each endpoint. The options are:
- This key can perform read-only chat actions
- This key can perform write-only chat actions
- This key can export data
- This key can perform read only contact actions
To read more about this and learn how to set up and maintain your Master API keys, click here.
The URL must contain the environment of your organisation:
https://{{environment}}.qwil.io/
Chat
- /chat-service/api/chats/create POST
- /chat-service/api/chats/rename POST
- /chat-service/api/chats/messages/send-text POST
- /chat-service/api/chats/invite POST
- /chat-service/api/chats/archive POST
- /chat-service/api/chats/export GET
- /chat-service/api/chats GET
- /chat-service/api/chats/messages/range GET
- /chat-service/api/chats/butler-says/send-text POST
Contacts
- /chat-service/api/contacts GET
- /chat-service/api/contacts/avatar GET
- /chat-service/api/contacts/list GET
- /chat-service/api/entity-memberships GET
Send files
chat-service/api/chats/create POST
The create API call allows you to create a chat, picking an "on behalf of" user and participants. For error codes click here.
Permissions: "This key can perform write-only chat actions"
Headers
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"entity_user_xref_uuids": ["{{entity_user_xref_uuid_sam_brown}}"],
"title": "Test"
}
chat-service/api/chats/rename POST
This API call allows you to rename a chat. Note: must be renamed 'on-behalf-of' a user in the chat. For error codes click here.
Permissions: "This key can perform write-only chat actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"chat_uuid": "{{chat_uuid}}",
"title": "Chat renamed"
}
chat-service/api/chats/messages/send-text POST
This API call allows you to message into a chat. Note: must be sent 'on-behalf-of' a user in the chat. For error codes click here.
Permissions: "This key can perform write-only chat actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"chat_uuid": "{{chat_uuid}}",
"text": "Message"
}
chat-service/api/chats/invite POST
This API call allows you to invite a user into a chat. Note: must be invited 'on-behalf-of' a user in the chat. For error codes click here.
Permissions: "This key can perform write-only chat actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"entity_user_xref_uuids": ["{{entity_user_xref_uuid_sarah_chamber}}"],
"chat_uuid": "{{chat_uuid}}"
}
chat-service/api/chats/archive POST
This API call allows you archive chat. Note: must be 'on-behalf-of' a user in the chat to archive. For error codes click here.
Permissions: "This key can perform write-only chat actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"chat_uuid": "{{chat_uuid}}",
"archived": true
}
chat-service/api/chats/export GET
This API call allows you export chat. Note: must be 'on-behalf-of' a user in the chat to export. For error codes click here.
Permissions: "This key can export data"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"chat_uuid": "{{chat_uuid}}"
}
chat-service/api/chats GET
This API retrieves information about a chat. Note: must be 'on-behalf-of' a user in the chat. For error codes click here.
Permissions: "This key can perform read-only chat actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"chat_uuid": "{{chat_uuid}}"
}
chat-service/api/chats/messages/range GET
Retrieves specific messages from a chat within a sequence range. Sequence argument is the message number, including chat creation and inviting new participants. Note: must be 'on-behalf-of' a user in the chat. For error codes click here.
Permissions: "This key can perform read-only chat actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"chat_uuid": "{{chat_uuid}}",
"from_seq": "0",
"to_seq": "2"
}
chat-service/api/chats/butler-says/send-text POST
Sends a message from the butler to a user. For error codes click here.
Permissions: "This key can perform write-only chat actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
Body
{
"entity_user_xref_uuid": "{{entity_user_xref_uuid_sam_brown}}",
"text": "Welcome to Qwil Messenger"
}
chat-service/api/contacts GET
Obtains the contact information of a user in another user's contacts. Note: the user who's contacts are being viewed must be connected to the user searched for. For error codes click here.
Permissions: "This key can perform read-only contact actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"entity_user_xref_uuid": "{{entity_user_xref_uuid_sam_brown}}"
}
chat-service/api/contacts/avatar GET
Obtains the avatar of a user in another user's contacts. Note: the user who contact list is being viewed must be connected to the user searched for. For error codes click here.
Permissions: "This key can perform read-only contact actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"entity_user_xref_uuid": "{{entity_user_xref_uuid_sam_brown}}"
}
chat-service/api/contacts/list GET
Obtains all users in a user's contact list. For error codes click here.
Note: this searches for contacts type, i.e 0- all, 1- staff, 2- clients.
Permissions: "This key can perform read-only contact actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"contact type": "0",
"page": "1",
"per_page": "100",
}
chat-service/api/entity-memberships GET
Obtains information about a user. For error codes click here.
Permissions: "This key can perform read-only contact actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body
{
"identifier": "{{identifier_sam_brown}}"
}
chat-service/api/chats/messages/send-file POST
Send a file on behalf of a user. For error codes click here.
Permissions: "This key can perform write-only chat actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body (cURL)
--form 'chat_uuid=00360a27-de0d-44dd-96d1-14ffc42c4603' \
--form 'file=@/Users/nimaakbari/Documents/apilist.xlsx' \
--form 'caption=example'
chat-service/api/chats/messages/send-image POST
Send an image on behalf of a user. For error codes click here.
Permissions: "This key can perform write-only chat actions"
Headers
X-MASTER-USER-API-KEY:{{X-MASTER-USER-API-KEY}}
X-MASTER-USER-API-KEY-SECRET:{{X-MASTER-USER-API-KEY-SECRET}}
Content-Type:application/json
on-behalf-of:{{entity_user_xref_uuid_james_harrow}}
Body (cURL)
--form 'chat_uuid=00360a27-de0d-44dd-96d1-14ffc42c4603' \
--form 'image=@/Users/nimaakbari/Documents/apilist.xlsx' \
--form 'caption=example'