API - Documentação (v1)

Para utilizar a API é necessário solicitar a ativação deste recurso na sua conta do ChatGuru. Os dados ficam disponíveis na página "Celulares", apenas usuários com permissão ADMIN tem acesso.

Neste exemplo estamos utilizando o endpoint "https://app.zap.guru/api/v1", verifique em sua conta qual é o endpoint que deve ser utilizado.

Parâmetros obrigatórios em todas as requisições

POST https://app.zap.guru/api/v1

Os parâmetros a seguir são obrigatórios em todas as requisições de nossa API, devem ser sempre incorporados com o restante das requisições.

Path Parameters

Name	Type	Description
chat_number	string	Número completo do WhatsApp, código do país, código de área e número, ex. 5511999999999
key	string	Sua chave da API
account_id	string	ID de sua conta ChatGuru
phone_id	string	ID do aparelho cadastrado no ChatGuru

200

Enviar Mensagem (message_send)

POST https://app.zap.guru/api/v1?key=KEY&account_id=ACCOUNT_ID&phone_id=PHONE_ID&action=message_send&send_date=SEND_DATE&text=TEXT&chat_number=CHAT_NUMBER

Envia uma mensagem para um chat que já encontra-se previamente cadastrado no ChatGuru.

Headers

Name	Type	Description
send_date	string	Data, Hora e Minuto para envio da mensagem. Formato: YYYY-MM-DD HH:MM
action	string	Ação desejada, neste caso "message_send"
text	string	Texto da mensagem.

201 O retorno das requisições é disponibilizado em formato JSON

{
  "code": 201,
  "result": "success",
  "description": "Mensagem cadastrada com sucesso!",
  "message_id": "5dd69cde00078e1be17fffd4",
  "message_status": "scheduled"
}

400 O retorno das requisições é disponibilizado em formato JSON

{
  "code": 400,
  "description": "account_id inválida",
  "result": "error"
}

Verificar Status da Mensagem (message_status)

POST https://app.zap.guru/api/v1?key=KEY&account_id=ACCOUNT_ID&phone_id=PHONE_ID&action=message_status&message_id=MESSAGE_ID

Retorna o status da mensagem

Headers

Name	Type	Description
action	string	Ação desejada, neste caso "message_status"
message_id	string	ID da mensagem recebida em resposta ao método message_send

200 O retorno das requisições é disponibilizado em formato JSON

{
  "message_status": "sent",
  "result": "success",
  "code": 200
}

400 O retorno das requisições é disponibilizado em formato JSON

{
  "description": "message_id inválida",
  "result": "error",
  "code": 400
}

Cadastrar um chat (chat_add)

POST https://app.zap.guru/api/v1?key=KEY&account_id=ACCOUNT_ID&phone_id=PHONE_ID&action=chat_add&name=NAME&text=TEXT&chat_number=CHAT_NUMBER&user_id=USER_ID&dialog_id=DIALOG_ID

Permite cadastrar um chat apenas se o recurso de "Adicionar Chats"estiver ativo em sua conta. O retorno das requisições é disponibilizado em formato JSON, o campo chat_add_id é informado neste retorno contendo o id que pode ser utilizado para verificar se o chat foi inserido ou houve algum erro durante a inserção.

Path Parameters

Name	Type	Description
dialog_id	String	ID do diálogo do chatbot que deseja executar para o chat após ele ter sido incluído com sucesso
action	string	Ação desejada, neste caso "chat_add"
name	string	Nome do chat que deseja cadastrar
text	string	Texto da mensagem inicial para o chat.
user_id	string	ID do usuário do ChatGuru para quem deseja delegar o chat automaticamente.

201 O retorno com sucesso não indica que o chat foi inserido com sucesso no ZapGuru, este retorno aponta apenas que ele foi cadastrado para ser inserido pelo ZapGuru. Utilize a ação chat_add_status para verificar se o chat foi criado e iniciado corretamente.

{
 "code": 201,
 "result": "success",
 "description": "Chat cadastrado para inclusão com sucesso!",
 "chat_add_id": "5dd69c2300078e1be17fffd4",
 "chat_add_status": "pending"
}

400

{
 "code": 400,
 "description": "Número não informado",
 "result": "error"
}

Verifica cadastro do Chat (chat_add_status)

POST https://app.zap.guru/api/v1?key=KEY&account_id=ACCOUNT_ID&phone_id=PHONE_ID&action=chat_add_status&chat_add_id=CHAT_ADD_ID

Retorna o status do cadastro do chat da ação "chat_add".

Path Parameters

Name	Type	Description
action	string	Ação desejada, neste caso "chat_add_status"
chat_add_id	string	ID do cadastro do chat informado no retorno de sucesso da ação "chat_add"

200 O retorno das requisições é disponibilizado em formato JSON. No caso de sucesso o item chat_add_status pode ser:: - pending → cadastro ainda está pendente - fetched → cadastro está em andamento - done → cadastro realizado, o chat foi incluído com sucesso. - error → houve um erro ao inserir o chat (número inválido, telefone desconectado, etc.)

{
 "chat_add_id": "5e3e9c0f52313722bd2e11a2",
 "chat_add_status": "done",
 "chat_add_status_description": "Chat adicionado com sucesso!",
 "result": "success",
 "code": 200
}

400

{
 "description": "chat_add_id não encontrado",
 "result": "error",
 "code": 400
}

Atualiza Campos Personalizados (chat_update_custom_fields)

POST https://app.zap.guru/api/v1?key=KEY&account_id=ACCOUNT_ID&phone_id=PHONE_ID&action=chat_update_custom_fields&chat_number=NUMERODOCHAT&field__NOME_DO_CAMPO=NOMEDOCAMPO

Permite atualizar os campos personalizados do chat através da API. O ID de cada campo pode ser encontrado no Gerenciador de Campos Personalizados

Query Parameters

Name	Type	Description
action	string	Ação desejada, nesse caso: "chat_update_custom_fields"
field__NOME_DO_CAMPO	string	Valor do campo personalizado

200 O retorno das requisições é disponibilizado em formato JSON.

{
  "chat_id": "5e52b639600ce7d9be01f6cd", 
  "code": 200, 
  "description": "Campos personalizados foram salvos.", 
  "result": "success"
}

400

{
  "code": 400, 
  "description": "Chat n\u00e3o encontrado n\u00e3o encontrado.", 
  "result": "error"
}

Adiciona Anotação (note_add)

POST https://app.zap.guru/api/v1

Permite adicionar anotações em um determinado chat via API

Query Parameters

Name	Type	Description
note_text	string	Texto de sua anotação
action	string	Ação desejada, nesse caso "note_add"

200

{
  "code": 200,
  "description": "Anotação criada com sucesso",
  "note_id": "5ebbc4ded8d8eaf9919970a9",
  "result": "success"
}

400

{
  "code": 400,
  "description": "Chat não encontrado.",
  "result": "error"
}

Executar diálogo (dialog_execute)

POST https://app.zap.guru/api/v1

Permite executar um diálogo em um chat existente

Query Parameters

Name	Type	Description
action	string	Ação desejada, nesse caso "dialog_execute"
dialog_id	string	ID do diálogo que será executado

200

{
  "code": 200,
  "dialog_execution_return": "Diálogo executado",
  "result": "success"
}

400

{
  "code": 400,
  "description": "Diálogo não encontrado para o phone_id informado. Verifique se o phone está atribuido corretamente ao chatbot.",
  "result": "error"
}

Enviar um Arquivo (message_file_send)

POST https://app.zap.guru/api/v1

Permite enviar um arquivo para um chat existente

Query Parameters

Name	Type	Description
caption	string	Nome do seu arquivo
file_url	string	O link de URL do arquivo
action	string	message_file_send

200