API Reference
=============

The AskHandle API is organized around `REST`_. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.

.. _REST: https://en.wikipedia.org/wiki/Representational_State_Transfer

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: https://curl.haxx.se/

::

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

.. image:: _static/chatbot_api.svg
    :width: 100%



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": "mary@example.com",
        "nickname": "Mary",
        "room": {
          "uuid": "de1e39a5-a391-4d7f-836d-cf3589529af8"
        }
      }'

**Example Response**
::

    {
        "uuid": "ffb84155-5f12-4bee-bd50-3c868097e473",
        "nickname": "Mary",
        "email": "mary@example.com",
        "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 AskHandle, you must always return a 200 OK HTTP response. Failing to do so may cause your webhook to be unsubscribed by the AskHandle.

**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": "mary@example.com",
            "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).