Entrar
Documentação

Desenvolvedores

Bots de suporte

Crie bots e responda nos chats da loja pela API.

Um bot é um autor com nome e ícone próprios no chat da loja. Use para responder dúvidas, enviar status de pedido ou registrar informações para a equipe. Todas as rotas exigem a permissão PROMISSE_BOT.

Rotas#

Rota Corpo ou query Resposta
GET /bot { "bots": [{ id, name, icon, createdAt }] }
POST /bot name, icon opcional { message, bot }
PUT /bot id, name, icon (URL ou null) { message, bot }
DELETE /bot?id=<uuid> { message }
POST /bot/send-message chat, bot_id, message, ephemeral, embed { message }

bot traz id, name, icon, loja, createdAt e updatedAt. Cada loja pode ter até 25 bots. Acima disso, a resposta é 409 limit_reached.

Terminal
curl -X POST "https://api.promisse.store/api/v1/bot" \
  -H "x-api-key: $PROMISSE_KEY" \
  -H "content-type: application/json" \
  -d '{ "name": "Atendente", "icon": "https://exemplo.com/bot.png" }'

Enviar uma mensagem#

Envie message, embed ou os dois. O ID do chat chega pelos webhooks chat_created e chat_message.

Terminal
curl -X POST "https://api.promisse.store/api/v1/bot/send-message" \
  -H "x-api-key: $PROMISSE_KEY" \
  -H "content-type: application/json" \
  -d '{
    "chat": "UUID_DO_CHAT",
    "bot_id": "UUID_DO_BOT",
    "message": "Seu pedido foi separado e sai hoje."
  }'
Campo Regra
chat UUID do chat
bot_id UUID do bot
message Texto, até 4000 caracteres
ephemeral true cria uma nota interna da equipe
embed Cartão com título, campos e imagens

Nota interna (ephemeral)#

Use ephemeral para registrar uma informação no chat sem o cliente ver:

Terminal
curl -X POST "https://api.promisse.store/api/v1/bot/send-message" \
  -H "x-api-key: $PROMISSE_KEY" \
  -H "content-type: application/json" \
  -d '{
    "chat": "UUID_DO_CHAT",
    "bot_id": "UUID_DO_BOT",
    "message": "Cliente com três reembolsos este mês.",
    "ephemeral": true
  }'

Para o comprador ver a mensagem, envie sem ephemeral ou com ephemeral: false.

Embed#

Campo Regra
title Até 256 caracteres
description Até 4000 caracteres
url Link http ou https
color { "bar": "#00b2ff" }
timestamp true mostra a data do envio
author { name, url, icon_url }
thumbnail { url }
image { url }
fields Até 10 itens: { title, subtitle, description, icon, url }
footer { text, icon_url }

Link que não seja http ou https é recusado.

Terminal
curl -X POST "https://api.promisse.store/api/v1/bot/send-message" \
  -H "x-api-key: $PROMISSE_KEY" \
  -H "content-type: application/json" \
  -d '{
    "chat": "UUID_DO_CHAT",
    "bot_id": "UUID_DO_BOT",
    "embed": {
      "title": "Pedido #1001",
      "description": "Pagamento aprovado.",
      "color": { "bar": "#21c985" },
      "fields": [{ "title": "Total", "description": "R$ 49,90" }],
      "footer": { "text": "Atendimento" },
      "timestamp": true
    }
  }'

Resposta#

JSON
{
  "message": {
    "id": "uuid", "chat": "uuid", "loja": "uuid", "deleted": false, "type": "bot", "author": "uuid", "edited": false,
    "message": "Seu pedido foi separado e sai hoje.", "embeds": [], "role": "bot", "ephemeral": false,
    "createdAt": "...", "updatedAt": "..."
  }
}

Erros#

Status code Quando
400 empty_message Sem message e sem embed.
400 invalid_embed Embed com campo ou link inválido.
400 message_too_long Texto acima do limite.
404 Chat ou bot não existe, ou é de outra loja.
409 chat_locked O chat está trancado.
429 chat_flood Mais de 30 mensagens de bot por minuto no mesmo chat.