Messaging / Bot API

Concepts

Un bot est un vrai compte GPChat (isBot: true) rattaché à votre application. Il peut envoyer et recevoir des messages exactement comme un utilisateur classique. Créez votre application et provisionnez un bot depuis l'espace développeur — la clé API générée porte automatiquement le scope messages:send.

Authentification

Toutes les requêtes utilisent une clé API dans l'en-tête Authorization :

Authorization: Bearer gpk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La clé doit porter le scope messages:send. Limite par défaut : 60 requêtes/minute par clé.

Envoyer un message privé

curl -X POST https://api.gpchat.app/v1/messages \
  -H "Authorization: Bearer gpk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "UID_DESTINATAIRE",
    "type": "text",
    "content": "Bonjour depuis mon intégration !"
  }'

Envoyer un message de groupe

Mêmes champs que ci-dessus, avec groupId à la place de to. Le bot doit être membre du groupe.

curl -X POST https://api.gpchat.app/v1/messages/group \
  -H "Authorization: Bearer gpk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "groupId": "GROUP_ID", "type": "text", "content": "Bonjour tout le monde !" }'

Recevoir des messages (webhooks)

Configurez un webhookUrl sur votre application pour recevoir les messages adressés à votre bot en temps réel. GPChat envoie une requête POST signée à chaque nouveau message :

POST <votre webhookUrl>
Content-Type: application/json
X-GPChat-Event: message.received
X-GPChat-Signature: t=1699999999,v1=<hmac_hex>

{
  "type": "message.received",
  "data": {
    "from": "UID_EXPEDITEUR",
    "msgId": "...",
    "chatId": "...",
    "type": "text",
    "textMsg": "Bonjour !"
  }
}

Les messages de groupe utilisent l'événement group_message.received (mêmes champs, plus groupId).

Vérifier la signature

La signature HMAC-SHA256 porte sur {timestamp}.{corps brut de la requête}, avec votre webhookSecret :

const [t, v1] = signatureHeader.replace('t=', '').split(',v1=');
const expected = crypto.createHmac('sha256', webhookSecret)
  .update(`${t}.${rawBody}`).digest('hex');
// comparer expected et v1 en temps constant (crypto.timingSafeEqual)

Codes d'erreur