API Reference¶
The Handle API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.
Authentication¶
Authenticate your account when using the API by including your secret API key in the request. Your API key carry many privileges, so be sure to keep them secret! Do not share your secret API key in publicly accessible areas such GitHub, client-side code, and so forth.
To use your API key, include it in the Authorization HTTP header. The key should be prefixed by the string literal “Token”, with whitespace separating the two strings. For example:
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
The curl command line tool may be useful for testing token authenticated APIs. For example:
curl -X GET https://dashboard.askhandle.com/api/v1/<resource> \
-H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'
Retrieving a Token (API key)¶
When POST’ing to https://dashboard.askhandle.com/api/v1/auth/api-token with the following data (assuming this username / password exists): {"username": "test", "password": "test"}
curl -X POST https://dashboard.askhandle.com/api/v1/auth/api-token \
-H 'Content-Type: application/json' \
-d '{"username": "test", "password": "test"}'
you’ll receive something that looks like the following:
{'token': '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'}
API Diagram¶
Resources¶
Lead¶
The lead object
Attributes | |
---|---|
uuid | string, UUID |
nickname | string, |
string, Email | |
phone_number | string, |
device | string, |
from_page_title | string, |
referrer | string, |
created_at | string, |
Available methods
- list:
GET /api/v1/leads/
List all your leads. - create:
POST /api/v1/leads/
Create a new lead. - retrieve:
GET /api/v1/leads/<uuid>/
Show the details of a specific lead. - update:
PUT /api/v1/leads/<uuid>/
Update all fields of a specific lead. - partial update:
PATCH /api/v1/leads/<uuid>/
Update a field of a specific lead. - destroy:
DELETE /api/v1/leads/<uuid>/
Delete a specific lead.
Available filters
Add GET parameters to your request in following format:
- start_date:
?start_date=YYYY-MM-DD
. - end_date:
?end_date=YYYY-MM-DD
. - start_date&end_date:
?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
. - limit:
?limit=<int>
.
Message¶
The message object
Attributes | |
---|---|
uuid | string, UUID |
nickname | string |
string, Email | |
phone_number | string |
body | string |
is_support_sender | boolean |
sent_at | datetime |
room | Room object (for POST request) |
Available methods
- list:
GET /api/v1/messages/
List all your messages. - create:
POST /api/v1/messages/
Create a new message. - retrieve:
GET /api/v1/messages/<uuid>/
Show the details of a specific message.
Example Request
Create a new message in an existing room:
curl -X POST https://dashboard.askhandle.com/api/v1/messages/ \
-H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' \
-H 'Content-Type: application/json' \
-d '{
"body": "Hello!",
"email": "[email protected]",
"nickname": "Mary",
"room": {
"uuid": "de1e39a5-a391-4d7f-836d-cf3589529af8"
}
}'
Example Response
{
"uuid": "ffb84155-5f12-4bee-bd50-3c868097e473",
"nickname": "Mary",
"email": "[email protected]",
"body": "Hello!",
"is_support_sender": false,
"sent_at": "2021-09-15T12:08:50.676405Z"
}
Room¶
The room object
Attributes | |
---|---|
label | string |
uuid | string, UUID |
name | string |
rating | integer, 1..5 |
is_bot_use | boolean |
created_at | datetime |
messages | array |
Available methods
- list:
GET /api/v1/rooms/
List all your rooms. - create:
POST /api/v1/rooms/
Create a new room. - retrieve:
GET /api/v1/rooms/<label>/
Show the details of a specific room. - update:
PUT /api/v1/rooms/<label>/
Update all fields of a specific room. - partial update:
PATCH /api/v1/rooms/<label>/
Update a field of a specific room. - destroy:
DELETE /api/v1/rooms/<label>/
Delete a specific room.
Webhook¶
When you receive a webhook event from the Handle, you must always return a 200 OK HTTP response. Failing to do so may cause your webhook to be unsubscribed by the Handle.
The webhook object
Attributes | |
---|---|
uuid | string, UUID |
event | string, Webhook Event |
target | string, Url |
Webhook Event | |
---|---|
chat.added | Subscribes to Room events |
message.added | Subscribes to Message events |
lead.added | Subscribes to Lead events |
lead.changed | Subscribes to Lead events |
Payload | |
---|---|
data | Subscribed object |
webhook | Webhook object |
Available methods
- list:
GET /api/v1/webhooks/
List all your webhooks. - create:
POST /api/v1/webhooks/
Create a new webhook. - retrieve:
GET /api/v1/webhooks/<uuid>/
Show the details of a specific webhook. - update:
PUT /api/v1/webhooks/<uuid>/
Update all fields of a specific webhook. - partial update:
PATCH /api/v1/webhooks/<uuid>/
Update a field of a specific webhook. - destroy:
DELETE /api/v1/webhooks/<uuid>/
Delete a specific webhook.
Example Request
List all your webhooks:
curl -X GET https://dashboard.askhandle.com/api/v1/webhooks/ \
-H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'
Create a new webhook:
curl -X POST https://dashboard.askhandle.com/api/v1/webhooks/ \
-H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' \
-H 'Content-Type: application/json' \
-d '{"event": "lead.added", "target": "http://127.0.0.1/"}'
Example Response
{
"uuid": "273dcd5c-64e6-4560-a777-0b52caac9615",
"event": "message.added",
"target": "http://127.0.0.1/"
}
Example Payload
{
"data": {
"uuid": "d8a2e337-9d4d-4515-979a-6f590379848f",
"body": "Hello!",
"email": "[email protected]",
"nickname": "Mary",
"is_support_sender": false,
"sent_at": "2021-09-15T13:06:12.373601+00:00"
},
"webhook": {
"uuid": "273dcd5c-64e6-4560-a777-0b52caac9615",
"event": "message.added",
"target": "http://127.0.0.1/"
}
}
Widget¶
The widget object
Attributes | |
---|---|
uuid | string, UUID |
token | string |
name | string |
domain | string, Url |
greeting_message | string |
contact_message | string |
header_title | string |
header_subtitle | string |
chat_subtitle | string |
name_placeholder | string |
email_placeholder | string |
phone_placeholder | string |
message_placeholder | string |
start_button_caption | string |
is_ask_name | boolean |
is_ask_email | boolean |
is_ask_phone | boolean |
logo_large | string, Url |
bot_avatar | string, Url |
bot_message_position | string, ‘center’, ‘left’ or ‘right’ |
is_show_bot_avatar | boolean |
use_new_button | boolean |
color | string |
vertical_align | string, ‘center’, ‘top’ or ‘bottom’ |
horizontal_align | string, ‘center’, ‘left’ or ‘right’ |
popup_timeout | integer, in sec |
is_bot_use | boolean |
Available methods
- retrieve*:
GET /api/v1/widgets/?token=<widget_token>
Show the details of a specific widget. - update:
PUT /api/v1/widgets/<widget_token>/
Update all fields of a specific widget. - partial update:
PATCH /api/v1/widgets/<widget_token>/
Update a field of a specific widget.
Note
The retrieve method GET /api/v1/widgets/?token=<widget_token>
is public (doesn’t require Token Authorization).