Huggy

API v2

Welcome to the Huggy API. With it, you can manage all agents, contacts and serve your customers, send and receive messages. This API allows you to programmatically perform actions on your company account.

Our API natively supports the format:

  • REST

    The system should make a request for the URL https://api.huggy.app/v2, sending the parameters by GET, POST, PUT or DELETE. For each request, the response will be a JSON object, which is detailed throughout this documentation.

Authentication

The authentication of APIv2 is made upon the token of access that can by which can be purchased by a platform accountde, as shown in the image below:

Autenticação APIv2

For this, you must provider a header of authorization in each request made, following the format:

    X-Authorization: Bearer xxxxxxxxxx
1

Headers

All requests must also include the following headers:

  • Content-Type: application/json
  • Accept: application/json
  • Authorization: Bearer xxxxxxx

Language

By default, when not informed the Accept-Language, all requests will be answered in english. For get the response at a preferred language, in the header of your request, enter:

  • Accept-Language: en
  • Accept-Language: pt-br
  • Accept-Language: es

Request

By default, all calls in API define that the request is being made directly at the main company. That is: the first company an agent was linked to. If a request are being made at a secondary company, it must assume the URI model https://api.huggy.io/v2/companies/{companyID}/resource...

Response

Some requests successful can be answered with a status 200 or 204 without a body returning, such as requests that are using POST and DELETE methods.

Pagination

The request parameter is available to all endpoint that list a resource content being accessed.
This list is limited to 20 results and the remaining resource, if exists, can be accessed with a search parameter ?page=1 in one request url. This page start in 0 (first page). If the requested page does not exist, a empty list [] will be returned in the request body.

Usual server responses:

  • 200 OK - The request was successful.
  • 201 Created - The request was successful and a resource was created.
  • 204 Modified - The request was successful and a resource was modified.
  • 400 Bad Request - The request could not be understood or was missing required parameters. Check the reason in the body response.
  • 401 Unauthorized - Authentication failed or user doesn't have permissions for requested operation. Check the API token, he may be wrong.
  • 403 Forbidden - The customer doesn’t have permission to content, the server is reserved to don’t give more answers. Different from code 401, the customer identity is known.
  • 404 Not Found - Resource was not found. This could be caused by a non existent ID.
  • 423 Locked - The resource being accessed is blocked, not being possible, at the time, to interact with it.
  • 501 Request Failed - May be caused by wrong method of request.

Agentes

GET/agents

List all agents

Get the list of all company agents.

Response 200

[
    {
        "id": 12162,
        "name": "John Doe"
    },
    {
        "id": 11839,
        "name": "Nicolas Tesla"
    },
    {
        "id": 11433,
        "name": "Linus Torvalds"
    },
    {
        "id": 11432,
        "name": "Dennis Ritchie"
    }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

GET/agents/{id}

View an agent detail

Get the data of a agent by your ID.

Parameters Type Example Description
id number 34146 Agent identifier number

Response 200

{
    "id": "34146",
    "name": "John Doe",
    "email": "john@doe.com",
    "login": "johndoe",
    "type": 3,
    "phone": "551199999999"
}
1
2
3
4
5
6
7
8

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

POST/agents

Create a new agent

Invite a new agent for Huggy platform.

Note: A new agent will only be visible after accepting email confirmation.

Attribute Type Description Required
email string Email of new agent Yes
type int Agent access scope definition Yes

Request Example

{
  "email": "john@doe.com",
  "type": 1
}
1
2
3
4

An agent is defined for your access perfil, this is represented for attribute type that receive a numeric value, at whare:

Definition Attribute Value
Agent Type 1
Manage Type 2
Administrator Type 3

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 500

{
    "reason": "agent already logged in"
}
1
2
3

PUT/agents/{id}

Update a agent

Update the agent data.

Note: This field password must have less than eight characters.

Parameters Type Example Description
id number 34146 Agent identifier number
Attribute Type Description Required
name string Agent name Yes
login string Agent login Yes
email string Agent email address No
password string Agent password No
type int Agent scope definition No
phone string Agent phone No
active boolean Definition of activity of agent in plataform No

Request Example

    {        
        "name": "John Doe",        
        "login": "johndoe",
        "email": "john@doe.com",
        "password": "12345678",
        "type": 2,
        "phone": "551199999999",
        "active": true
    }
1
2
3
4
5
6
7
8
9

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Contatos

GET/contacts

List all contacts

Get the list of all contacts.

Note: The return of payload of this request have an attribute customFields. A list that empty returned if you does not have custom field registred.

Response 200

[
    {
        "id": 8307934,
        "name": "John",
        "email": john@doe.com,
        "mobile": 1199999999,
        "phone": 1133333333,
        "customFields": []
    },
    {
        "id": 8227983,
        "name": "Tesla",
        "email": "nicolas@tesla.com",
        "mobile": "1199999999",
        "phone": "1133333333",
        "birthday": null,
        "customFields": {
            "segundo_email_customer": "nicolas@dev.com",
            "cpf_customer": "03600000041",
            "data_customer": "14/10/2019",
            "hora_customer": "20:30",
            "numero_customer": "104",
            "perfil_customer": "Nivel 5",
            "telefone_customer": "+557599999999",
            "cnpj_customer": "00.000.000/0001-00"
        }
    }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

GET/contacts/{id}

View a contact details

Get the data of a contact by your ID.

Parameters Type Example Description
id number 8227983 Contact identifier number

Response 200

{
    "id": 8227983,
    "name": "John",
    "email": "john@doe.com",
    "mobile": "1199999999",
    "phone": "1133333333",
    "birthday": null,
    "customFields": {
        "segundo_email_customer": "john@doe.com",
        "cpf_customer": "03600000041",
        "data_customer": "14/10/2019",
        "hora_customer": "20:30",
        "numero_customer": "104",
        "perfil_customer": "Nivel 5",
        "telefone_customer": "+551199999999",
        "cnpj_customer": "00.000.000/0001-00"
    },
    "channels": {
        "voip": true,
        "messenger": false,
        "widget": false,
        "telegram": true,
        "whatsapp": false,
        "email": true,
        "sms": true,
        "telegramBot": false,
        "whatsappApi": false
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

PUT/contacts/{id}

Update a contact

Update a contact by your ID.

Parameters Type Example Description
id number 5081748 Contact identifier number
Attributes Type Description Required
name string Contact name Yes
email string Contact email Yes
phone string Contact phone Yes
mobile string Contact mobile No
address string Contact address No
city string Contact city No
district string Contact district NO
state string Contact state No
obs string Comment done about contact No

Note: Among the attributes that must be passed in the request body, name, email or phone is required.

Request Example

{  
  "name": "john Doe",  
  "email": "john@doe.com",
  "mobile": "1199999999", 
  "phone": "1133333333",
  "address": "Rua Roque Petroni JR",
  "city": "São Paulo",
  "district": "Morumbi",
  "state": "São Paulo",
  "obs": "This is a field for added subjects about the contact"
}
1
2
3
4
5
6
7
8
9
10
11

Response 204

Successful request with empty body
1

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 404

{
   "reason": "This message will show that doesn't exist result for your search"
}
1
2
3

DELETE/contacts/{id}

Delete a contact

Delete a contact by your ID.

Parameters Type Example Description
id number 5082105 Contact identifier number

Request Example

{

}
1
2
3

Response 204

Successful request with empty body
1

Chats

GET/chats

List all chats

Get the list of all chats.

Response 200

[
    {
        "id": 13123230,
        "agentId": 34146,
        "secondAgentId": 8792,
        "contactId": null,
        "siteCustomerId": null,
        "messengerId": null,
        "departmentId": null,
        "tabulationId": null,
        "channels": [],
        "queueNumber": null,
        "createdAt": "2019-10-29 16:06:00",
        "updatedAt": "2019-10-29 16:06:00",
        "attendedAt": null,
        "closedAt": null
    },
    {
        "id": 13123115,
        "agentId": 34146,
        "secondAgentId": null,
        "contactId": 5081376,
        "siteCustomerId": null,
        "messengerId": null,
        "departmentId": null,
        "tabulationId": null,
        "channels": [
            {
                "uuid": "325c3456-9981-43f5-8705-xxxxxxxxxxxx",
                "id": "john@doe.com",
                "name": "John Doe",
                "type": "Email"
            }
        ],
        "queueNumber": null,
        "createdAt": "2019-10-24 15:22:50",
        "updatedAt": "2019-10-24 15:23:00",
        "attendedAt": "2019-10-24 15:22:54",
        "closedAt": null
    },
    {
        "id": 13119881,
        "agentId": 34146,
        "secondAgentId": null,
        "contactId": 5081359,
        "siteCustomerId": null,
        "messengerId": null,
        "departmentId": null,
        "tabulationId": null,
        "channels": [
            {
                "uuid": "325c3456-9981-43f5-8705-xxxxxxxxxxxx",
                "id": "john@doe.com",
                "name": "John Doe",
                "type": "Email"
            }
        ],
        "queueNumber": null,
        "createdAt": "2019-06-11 11:44:10",
        "updatedAt": "2019-06-11 11:44:33",
        "attendedAt": "2019-06-11 11:44:14",
        "closedAt": null
    }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

GET/chats/{id}/messages

List chat messages

Get all messages of a chat by your ID.

Parameters Type Example Description
id number 13119881 Chat identifier number

Response 200

[
    {
        "id": 270964274,
        "body": "Olá, Hugo!",
        "is_internal": false,
        "is_email": false,
        "sender": {
            "id": 1842157,
            "name": "John Doe",
            "mobile": "551199999999",
            "phone": "551133333333",
            "email": "john@doe.com",
            "photo": "https://c.pzw.io/img/avatar-user-boy.jpg"
        },
        "senderType": "widget",
        "receiver": false,
        "receiverType": "agent",
        "file": null,
        "channel": "widget",
        "customer": {
            "id": 1842157,
            "name": "John Doe",
            "mobile": "551199999999",
            "phone": "551133333333",
            "email": "john@doe.com",
            "photo": "https://c.pzw.io/img/avatar-user-boy.jpg"
        },
        "chat": {
            "id": 13123541,
            "channel": "widget",
            "situation": "in_chat",
            "department": 23741,
            "customer": {
                "id": 1842157,
                "name": "John Doe",
                "mobile": "551199999999",
                "phone": "551199999999",
                "email": "john@doe.com",
                "photo": "https://c.pzw.io/img/avatar-user-boy.jpg"
            }
        },
        "send_at": "2019-11-21 15:08:45",
        "read_at": null,
        "type": "0",
        "eventType": null
    }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 404

{
   "reason": "This message will show that doesn't exist result for your search"
}
1
2
3

GET/chats/{id}/feedback

View satisfaction survey

Get the note and the message of satisfaction survery of informed chat.

Parameters Type Example Description
id number 13119881 Chat identifier number

Response 200

{
    "score": "5",
    "text": "We were very happy with the service"
}
1
2
3
4

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 404

{
   "reason": "This message will show that doesn't exist result for your search"
}
1
2
3

POST/chats/{channel}

Create a new chat

Create a new chat in platform, passing the chanel desired with url parameter.

The channels of chat can be:

  • 1: whatsapp
  • 2: email
  • 3: telegram
Attributes Type Description Required
name string Contact name Yes
phone string Contact phone Yes
email string Contact email address Yes
message string Send message in call opened No
department int Department identifier number No
subject string Subject message No
isInternal boolean Contact district No

Request Example

{
    "name": "John Doe",
    "phone": "551199999999",
    "email": "john@doe.com",
    "message": "Hello, John!",
    "department": "3",
    "subject": "",
    "isInternal": true
}
1
2
3
4
5
6
7
8
9

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

POST/chats/{id}/close

Close a chat

End a chat call by your ID.

Note: Define the parameter sendFeedback with true when you want the user to evaluate the service.

Parameters Type Example Description
id number 13119881 Chat identifier number

Request Example

{
    "sendFeedback": true
}
1
2
3

Response 201

Successful request with empty body
1

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 404

{
   "reason": "This message will show that doesn't exist result for your search"
}
1
2
3

POST/chats/{id}/queue

Put chat on queue

Put a chat in queue by your ID.

Note: Only chats that are in attendance by an agent can be queued.

Parameters Type Example Description
id number 13119881 Chat identifier number

Response 201

Successful request with empty body
1

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 404

{
   "reason": "This message will show that doesn't exist result for your search"
}
1
2
3

POST/chats/{id}/messages

Add new message in chat

Send a message for a chat. Set the isInternal parameter to true when you want to send an internal message to the chat.

Parameters Type Example Description
id number 13119881 Chat identifier number
Attribute Type Description Required
text string Text message send to chat Yes
isInternal boolean Inform if the chat is internal Yes

Request Example

{
    "text": "Hello John!",
    "isInternal": false
}
1
2
3
4

Response 201

Successful request with empty body
1

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 404

{
   "reason": "This message will show that doesn't exist result for your search"
}
1
2
3

POST /chats/{id}/situation

Change chat situation

Change a chat situation by your ID.

Parameters Type Example Description
id number 13119881 Chat identifier number
Attribute Type Description
auto string Chat in automatic distribution
wait_for_chat string Chat waiting for attendance
in_chat string Chat in attendance
blocked string Chat blocked for attendance

Request Example

{
    "situation": "wait_for_chat"
}
1
2
3

Response 201

Successful request with empty body
1

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 404

{
   "reason": "This message will show that doesn't exist result for your search"
}
1
2
3

POST/chats/{id}/tags

Define tags

Note: For the definition of more of a one tag, separate its per comma.

Parameters Type Example Description
id number 13119881 Chat identifier number
Attribute Type Description Required
tags string Tags that represents the subject of a determinate interaction Yes

Request Example

{
    "tags" : "tag1, tag2"
}
1
2
3

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 404

{
   "reason": "This message will show that doesn't exist result for your search"
}
1
2
3

POST/chats/{id}/flow

Execute flow

Run a Flow from a chat that is not finalized or is not internal. If the chat already has a Flow in process, it will be aborted and the execution of the new Flow will be started.

Parameters Type Example Description
id number 13119881 Chat identifier number
Attribute Type Description Required
flowId int Flow identifier number Yes

Request Example

{
    "flowId" : 142714
}
1
2
3

Response 200

Successful request with empty body
1

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 404

{
   "reason": "This message will show that doesn't exist result for your search"
}
1
2
3

POST/flows/{flowId}/contact/{contactId}/exec

Execute a flow to a contact

Initialize the execution of a flow to a specific contact.

Channels that can use this resource:

  • Email
  • Messenger
  • TelegramBot
  • Whatsapp

To specify the channel that will be used to execute the flow, it is necessary to send the uuid. This uuid is the universal identifier of the channel. The value of the uuid can be obtained at the Huggy panel bellow the section: Configuration >> Channels >> Channel Details.

Besides the uuid, there is more 4 attributes that can be provide during the request:

variables ( object )

Corresponds to the fields that can be used during flow execution.

"variables": { 
    "data": "15/10/2019",
    "url_evento": "https://huggy.io"
}
1
2
3
4

Running example

At the variables declaration above, there is two terms that can be used during the flow execution: data and url_evento. For these two terms to be used it is necessary to inform them in some part of the flow's action, for example, in the action of sending message.

When sending a message with the following text:

"Hello, good afternoon. The event will be on . The access link is the following: ".

The system will replace the terms data and url_event by the values provided at the variables declaration, being as fllows:

"Hello, good afternoon. The event will be on 15/10/2019. The access link is the following: https://huggy.io".

Note: default { }

whenInChat ( true | false )

If the chat is in attendance with the agent, the following conditions will be considered:

  • true: Execute the flow and remove the agent from the conversation (the chat will come back to the automatic status).

  • false: Do not execute the flow.

Note: default false

whenWaitForChat ( true | false )

If the chat is waiting on the queue, the following conditions will be considered:

  • true: Do not execute the flow.

  • false: The chat will come back to the automatic status.

Note: default false

whenInAuto ( true | false )

If it is on automatic and/or hold another flow im process, the following conditions will be considered:

  • true: Abort the actual flow and initialize the execution of the provided flow.

  • false: Do nothing.

Observations:
For the right operation of this resource in the channels Messenger and TelegramBot the provided contact must have a link with the company, that is, it is necessary that the contact has already done some service with the company through the mentioned channels.

  • In the case of whatsapp channel, it is possible to run the flow without previous service. However, the contact's phone number must be valid: Country Area Code (55-Brazil) + Area Code (DDD) + Phone Number. Ex. 5511988886666.

  • If any of the four attributes above explained is not provided at the request, the system will pick up the default value of each one.

  • If there is no open chat with the contact, a new chat will be created.

Parameters Type Example Description
flowId number 10082 Flow identifier number
contactId number 5080890 Contact identifier number

Request Example

{
  "uuid": "",
  "variables": {
    "data": "15/10/2019",
    "url_evento": "https://huggy.io"
  },
  "whenInChat": true,
  "whenWaitForChat": true,
  "whenInAuto": true
}
1
2
3
4
5
6
7
8
9
10

Response 200

{
    "reason": "Flow processed",
    "chatID": 19291350
}
1
2
3
4

Response 400

{
   "reason": "This message will inform what caused the error"
}
1
2
3

Response 404

{
   "reason": "This message will show that doesn't exist result for your search"
}
1
2
3

← API v3 →