This documentation represents an early alpha-version API. The Maqsam API is subject to change in the future.
All calls are authenticated with HTTP Basic Authentication. This allows for using curl -u "<access_key_id>:<access_secret>"
during testing.
Contact support@maqsam.com to enable the API feature for your account, then you can generate access_key_id
and access_secret
combination from the account settings.
The index endpoint is served on: https://api.maqsam.com/v1/agents
.
It will return a paginated list with a maximum of 100 entries per page of agents data including both active and inactive agents.
Calls to this endpoint use the HTTP GET verb, with MIME type application/x-www-form-urlencoded
.
Request params are:
* page
(optional): to specify the page number which its data is returned. 0 and 1 values will return the same page. Must be provided in the url:
https://api.maqsam.com/v1/agents/page/<page>
If it is not provided, the default is 0 i.e the first page.
The following three requests will return the same data:
- https://api.maqsam.com/v1/agents
- https://api.maqsam.com/v1/agents/page/0
- https://api.maqsam.com/v1/agents/page/1
If the API call fails, it returns an HTTP status code of 401
, or 500
, and a JSON
body with a message specifying the nature of the failure, for example:
{ "error":true, "message":"Unauthorized" }
The following table shows all the possible failure scenarios, and their associated messages and HTTP status codes.
Reason | Status Code | Message |
Authentication fails | 401 | "Unauthorized" |
In case of server-side error | 500 | "Internal Server Error" |
If the API call is successful, it returns an HTTP status code of 200
, with the following JSON
body, the message value is an array where each element represents an agent record
{ "result": "success", "message": "<array of agents>" }
Where each element of < array of agents >
contains the following fields:
identifier
: a unique identifier of the agent.name
: name of the agent.email
: email of the agent.active
: boolean value representing whether agent is active or inactive.groups
: the agents' groups.outgoingEnabled
: boolean value representing whether outgoing calls are enabled for this agent.incomingEnabled
: boolean value representing whether incoming calls are enabled for this agent.whatsappEnabled
: boolean value representing whether whatsapp conversations are enabled for this agent.state
: agent state in addition to timestamp representing the starting time of the state, state could be Available
, Busy
, Absent
or any other user-defined state. created_at
: Epoch time of the agent creation.