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,
email	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
email	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).