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

_images/chatbot_api.svg

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