API de Notificações

Introdução

A API de Notificações do Looqbox permite o envio de notificações individuais para usuários. Cada notificação é direcionada a um destinatário específico e exibida no feed geral, podendo também ser filtrada na aba de IA. Essa API é ideal para automação de alertas e comunicação personalizada.

Apenas o usuário destinatário e o remetente têm acesso à mensagem pela interface, garantindo comunicação direta e personalizada dentro da plataforma.

Setup

Para utilizar a API, o cliente deve requisitar um token de acesso. Esse token deve ser incluído no cabeçalho de cada requisição na chave Authorization.

Estrutura da Requisição

A requisição deve seguir o seguinte formato:

import requests
import json

url = "https://api.looqbox.com/v1/feed/ai"

payload = json.dumps({
  "message": {
    "title": "Teste",
    "body": "Conteúdo da notificação",
    "authorLogin": "admin",
    "recipientLogin": "dmurta",
    "question": "teste"
  },
  "metadata": {}
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {token}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Explicação dos Campos

• title: Título da notificação.

  • Deve possuir entre 1 e 30 caracteres

• body: Corpo da mensagem.

  • Deve possuir entre 1 e 280 caracteres

• authorLogin: Usuário que está enviando a mensagem.

• recipientLogin: Usuário que receberá a mensagem.

• question (opcional): Indica qual pergunta será feita no Looqbox caso o usuário clique na notificação.

• metadata (opcional): Campo para informações adicionais (ex: nome da campanha, tags para categorização etc)

Características da API

Correlação de Mensagens

É importante que o cliente salve o ID de cada mensagem enviada para que possa acompanhar seu status junto à equipe do Looqbox. Esse identificador é chamado de correlationId e permite rastrear cada etapa de envio da mensagem através do log do sistema.

Exemplo de resposta ao envio de uma mensagem:

{
    "id": "0194e1d8-c7bb-7246-af87-9ac1c5530cef",
    "message": "Message queued"
}

Limitações

A API possui restrições de taxa de envio (rate limits), que devem ser discutidas de acordo com cada cenário e o token do cliente.

Arquitetura

As mensagens são entregues por uma arquitetura de filas, o que pode resultar em um pequeno atraso entre o envio e a entrega. Esse tempo de processamento varia conforme o volume de mensagens, geralmente levando de alguns segundos a poucos minutos.

Casos de Erro

A API pode retornar os seguintes erros:

400 - Requisição Inválida

Retornado quando falta alguma informação obrigatória:

{
    "timestamp": "2025-02-07T19:16:54.707+00:00",
    "path": "/v1/feed/ai",
    "status": 400,
    "error": "Bad Request",
    "requestId": "1ce16afc-20691",
    "message": "invalid_payload"
}

429 - Limite de Requisições Excedido

Se o número de requisições superar o limite permitido para o token:

429 Too Many Requests

401 - Token Inválido

Caso o token de autenticação não seja válido:

401 Unauthorized