# API v2

Bem-vindo à API Huggy. Com ela, você pode gerenciar todos os agentes, contatos e atender seus clientes, enviar e receber mensagens. Essa API permite executar ações programaticamente na conta da sua empresa.

Nossa API nativamente suporta o formato:

• REST

  O sistema deve fazer uma solicitação para o URL https://api.huggy.app/v2, enviando os parâmetros por GET, POST, PUT ou DELETE. Para cada solicitação, a resposta será um objeto JSON, que é detalhado ao longo desta documentação.

# Autenticação

A autenticação da APIv2 é feita mediante o token de acesso que pode ser adquirido através de uma conta na plataforma conforme demonstrado na imagem abaixo:

Para isso, você deve fornecer um cabeçalho de Autorização em cada solicitação feita, seguindo o formato:

    X-Authorization: Bearer xxxxxxxxxx

# Headers

Todos os pedidos também devem incluir os seguintes headers:

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

# Idioma

Por padrão, quando não for informado o Accept-Language, todas as requisições serão respondidas em inglês. Para obter a resposta em um idioma preferido, no Header de sua requisição, informe:

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

# Requisições

Por padrão, todas as chamadas à API assumem que a requisição em questão está sendo feita diretamente na company principal. Isto é: a primeira company que um agente foi vinculado. Se a requisição está sendo feita a uma company secundária, ela deverá assumir o modelo de URI https://api.huggy.io/v2/companies/{companieId}/recurso...

# Response

Algumas requisições bem-sucedidas podem ser respondidas com um status 200 ou 204 sem que um corpo retorne, como em requisições que utilizam os métodos POST e DELETE.

# Paginação

O parâmetro de paginação está previsto para todos os endpoints que listam o conteúdo de um determinado recurso. Essa lista se limita a 20 resultados e os recursos remanescentes, se existirem, podem ser acessados com um parâmetro de consulta ?page=1 em uma requisição. Esta paginação começa em 0 (primeira página). Se a página solicitada não existir, uma lista vazia [] é retornada no corpo da resposta.

# Respostas usuais do servidor:

• 200 OK - o pedido foi bem sucedido.
• 201 Created - o pedido foi bem sucedido e um recurso foi criado.
• 204 Modified - o pedido foi bem sucedido e um recurso foi modificado.
• 400 Bad Request - o pedido não pôde ser entendido ou faltavam os parâmetros necessários. Verifique o motivo na resposta do corpo.
• 401 Unauthorized - falha na autenticação ou o usuário não possui permissões para a operação solicitada. Verifique o token da API, ele pode estar errado.
• 403 Forbidden - o cliente não tem direitos de acesso ao conteúdo, portanto, o servidor é reservado a não dar mais respostas. Diferente do código 401, aqui a identidade do cliente é conhecida.
• 404 Not Found - o recurso não foi encontrado. Isso pode ser causado por um ID não existente.
• 423 Locked - O recurso sendo acessado está bloqueado, não sendo possível, no momento, nenhuma interação com ele.
• 501 Request Failed - pode ser causada por um método de solicitação incorreto.

# Agentes

# GET/agents

Visualizar todos os agentes

Obtém a lista de todos os agentes da company.

Resposta 200

[
    {
        "id": 12162,
        "name": "John Doe"
    },
    {
        "id": 11839,
        "name": "Nicolas Tesla"
    },
    {
        "id": 11433,
        "name": "Linus Torvalds"
    },
    {
        "id": 11432,
        "name": "Dennis Ritchie"
    }
]

# GET/agents/{id}

Visualizar um agente

Obtém os dados de um agente através do seu ID.

Resposta 200

{
    "id": "34146",
    "name": "John Doe",
    "email": "john@doe.com",
    "login": "johndoe",
    "type": 3,
    "phone": "551199999999"
}

Resposta 400

{
    "reason": "Esta mensagem informará o que ocasionou o erro"
}

# POST/agents

Convidar um novo agente

Convida um novo agente para a plataforma Huggy.

Nota: Um novo agente só será visível após o aceite no e-mail de confirmação.

Exemplo da requisição

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

Um agente é definido pelo seu perfil de acesso, sendo este representado pela atributo type que recebe um valor numérico, onde:

Resposta 400

{
    "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 500

{
    "reason": "Agente já conectado"
}

# PUT/agents/{id}

Atualizar um agente

Atualiza os dados de um agente.

Note: O campo password deve conter pelo menos oito caracteres.

Exemplo da requisição

    {        
        "name": "John Doe",        
        "login": "johndoe",
        "email": "john@doe.com",
        "password": "12345678",
        "type": 2,
        "phone": "551199999999",
        "active": true
    }

Resposta 400

{
    "reason": "Esta mensagem informará o que ocasionou o erro"
}

# Contatos

# GET/contacts

Visualizar todos os contatos

Obtém a lista de todos os contatos.

Nota: O payload de retorno desta requisição possui um atributo customFields. Uma lista que retornará vazia caso não haja campos personalizados cadastrados.

Resposta 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"
        }
    }
]

# GET/contacts/{id}

Visualizar um contato

Obtém os dados de um contato através do seu ID.

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

# PUT/contacts/{id}

Atualizar um contato

Atualiza um contato através do seu ID.

Nota: Dentre os atributos que devem ser passados no corpo da requisição, name, email ou phone são obrigatórios.

Exemplo da Requisição

{  
  "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": "Esse é um campo para adicionar observações sobre o contato"
}

Resposta 204

Requisição bem sucedida com o body vazio

Response 400

{
   "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 404

{
   "reason": "Esta mensagem mostrará que não existe resultado para sua busca"
}

# DELETE/contacts/{id}

Excluir um contato

Exclui um contato através do seu ID.

Exemplo da Requisição

{

}

Resposta 204

Requisição bem sucedida com o body vazio

# Chats

# GET/chats

Visualizar todos os chats

Obtém a lista de todos os chats.

Resposta 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
    }
]

# GET/chats/{id}/messages

Listar mensagens

Obtém todas as mensagens de um chat através do ID do chat.

Resposta 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
    }
]

Response 400

{
   "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 404

{
   "reason": "Esta mensagem mostrará que não existe resultado para sua busca"
}

# GET/chats/{id}/feedback

Visualizar pesquisa de satisfação

Obtém a nota e a mensagem da pesquisa de satisfação do chat informado.

Resposta 200

{
    "score": "5",
    "text": "Ficamos muito contentes com o atendimento"
}

Response 400

{
   "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 404

{
   "reason": "Esta mensagem mostrará que não existe resultado para sua busca"
}

# POST/chats/{channel}

Criar um novo chat

Cria um novo chat na plataforma, passando o canal desejado como parâmetro na url.

Os canais de atendimento podem ser:

• 1: whatsapp
• 2: email
• 3: telegram

Exemplo da requisição

{
    "name": "John Doe",
    "phone": "551199999999",
    "email": "john@doe.com",
    "message": "Olá, John!",
    "department": "3",
    "subject": "",
    "isInternal": true
}

Resposta 400

{
    "reason": "Esta mensagem informará o que ocasionou o erro"
}

# POST/chats/{id}/close

Finalizar um atendimento

Finaliza um atendimento de chat através do ID do chat.

Nota: Defina o parâmetro sendFeedback como true quando o quiser que o usuário avalie o atendimento.

Exemplo da requisição

{
    "sendFeedback": true
}

Resposta 201

Requisição bem sucedida com o body vazio

Response 400

{
   "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 404

{
   "reason": "Esta mensagem mostrará que não existe resultado para sua busca"
}

# POST/chats/{id}/queue

Colocar atendimento na fila de espera

Coloca um chat na fila de atendimento através do ID do chat.

NOTA: Somente poderão ser colocados na fila chats que estiverem em atendimento por algum agente.

Resposta 201

Requisição bem sucedida com o body vazio

Response 400

{
   "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 404

{
   "reason": "Esta mensagem mostrará que não existe resultado para sua busca"
}

# POST/chats/{id}/messages

Enviar Mensagem

Envia uma mensagem para um chat. Defina o parâmetro isInternal como true quando quiser enviar uma mensagem interna para o chat.

Exemplo da requisição

{
    "text": "Olá John!",
    "isInternal": false
}

Resposta 201

Requisição bem sucedida com o body vazio

Response 400

{
   "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 404

{
   "reason": "Esta mensagem mostrará que não existe resultado para sua busca"
}

# POST /chats/{id}/situation

Alterar a situação do chat

Altera a situação do chat a partir do ID.

Exemplo da requisição

{
    "situation": "wait_for_chat"
}

Resposta 201

Requisição bem sucedida com o body vazio

Response 400

{
   "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 404

{
   "reason": "Esta mensagem mostrará que não existe resultado para sua busca"
}

# POST/chats/{id}/tags

Definir tags

Nota: Para a definição de mais de uma tag, separe-as por vírgula.

Exemplo da Requisição

{
    "tags" : "tag1, tag2"
}

Response 400

{
   "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 404

{
   "reason": "Esta mensagem mostrará que não existe resultado para sua busca"
}

# POST/chats/{id}/flow

Executar flow

Execute um Flow a partir de um chat que não esteja finalizado ou que não seja do tipo interno. Caso o chat já possua um Flow em processamento, este será abortado e a execução do novo Flow será iniciada.

Exemplo da Requisição

{
    "flowId" : 142714
}

Resposta 200

Requisição bem sucedida com o body vazio

Response 400

{
   "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 404

{
   "reason": "Esta mensagem mostrará que não existe resultado para sua busca"
}

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

Executar um flow para um contato

Inicializa a execução de um flow para um contato específico.

Canais que podem utilizar este recurso:

• Email
• Messenger
• TelegramBot
• Whatsapp

Para especificar o canal que será utilizado para executar o flow, é necessário o envio do uuid, que corresponde ao identificador universal do canal. O valor do uuid pode ser obtido no painel Huggy em "configurações" >> "canais" >> "canal desejado" >> detalhamento do canal.

Além do uuid, existem mais 4 atributos que podem ser informados durante a requisição:

variables ( object )

Corresponde aos campos que podem ser utilizados durante a execução do flow.

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

Exemplo de funcionamento

Na declaração de variables acima, existem dois termos que podem ser utilizados durante a execução do flow: data e url_evento. Para que esses dois termos sejam utilizados é necessário informá-los em alguma parte das ações do flow, por exemplo, na ação de enviar mensagem.

Ao enviar uma mensagem com o seguinte texto:

"Olá, boa tarde. O evento será no dia . Segue o link de acesso ".

O sistema irá substituir os termos data e url_evento pelos valores informados na declaração das variáveis, ficando da seguinte maneira:

"Olá, boa tarde. O evento será no dia 15/10/2019. Segue o link de acesso https://huggy.io".

Nota: default { }

Se o chat estiver em atendimento com o agente, as seguintes condições serão levadas em consideração:

• true: Executa o flow e remove o agente da conversa (o chat volta para o status automático).

• false: Não executa o flow.

Nota: default false

Se o chat estiver na fila, são levadas em consideração as seguintes condições:

• true: Não executa o flow.

• false: Chat volta para o status automático.

Nota: default false

Se estiver em automático e/ou possuir outro flow em processamento, serão levadas em consideração as seguintes condições:

• true: Abortar o flow atual e iniciar a execução do flow informado.

• false: Não faz nada.

Nota: default false

Observações:
Para o funcionamento deste recurso nos canais Messenger e TelegramBot o contato informado precisa ter vínculo com a empresa, ou seja, é necessário que o contato já tenha feito algum atendimento com a empresa pelos canais citados

• No caso do canal whatsapp, é possivél executar o flow sem que tenha existido um atendimento anterior. No entanto, o número do telefone do contato precisa estar válido: Código de área do país (55-Brasil) + código de área do estado (DDD) + o número do telefone. Ex. 5511988886666.

• Caso algum dos quatros atributos explicados acima não seja informado na requisição, o sistema pegará o valor default de cada um.

• Se não houver um chat aberto com o contato, será criado um novo chat.

Exemplo da requisição

{
  "uuid": "",
  "variables": {
    "data": "15/10/2019",
    "url_evento": "https://huggy.io"
  },
  "whenInChat": true,
  "whenWaitForChat": true,
  "whenInAuto": true
}

Resposta 200

{
    "reason": "Flow processed",
    "chatID": 19291350
}            

Resposta 200

{
    "reason": "Flow processed and agent removed from chat",
    "chatID": 19291350
}   

Response 400

{
   "reason": "Esta mensagem informará o que ocasionou o erro"
}

Resposta 404

{
   "reason": "Esta mensagem mostrará que não existe resultado para sua busca"
}