Você quer ter, em outro lugar (um CRM, um data warehouse, uma planilha, um relatório), o histórico completo do que foi conversado com cada lead. As mensagens de WhatsApp e E-mail que acontecem dentro do GS Engage podem ser lidas pela API e copiadas para onde você precisar.

Esta página mostra como fazer isso em dois passos: primeiro você lista as conversas (chamamos de threads), depois puxa as mensagens de cada uma.

Você vai precisar de uma apiKey (a sua chave de acesso à API). Ela é criada na plataforma em Configurações > Configurações de API e é enviada como parâmetro na própria URL, no formato ?apiKey=SUA_CHAVE.

Se ainda não validou sua chave, dê uma passada rápida pelo Quickstart da API — lá explicamos como confirmar que a chave funciona antes de qualquer outra chamada.

O modelo é simples e tem dois níveis:

graph LR
A["Lead"] --> B["Thread (uma conversa por canal)"]
B --> C["Mensagem"]
B --> D["Mensagem"]
B --> E["Mensagem"]

• Thread é uma conversa — um fio de diálogo por canal. Um mesmo lead pode ter uma thread de WhatsApp e outra de E-mail.
• Mensagem é cada troca dentro daquela thread (o que foi enviado e o que foi recebido).

Por isso a leitura acontece em duas etapas: você lista as threads para descobrir quais conversas existem e, com o identificador de cada uma, puxa as mensagens dela.

curl "https://api.gsengage.com/api/v1/conversations/threads?apiKey=SUA_CHAVE&limit=20&page=1"

{
  "data": [
    {
      "id": "652f1a9c8b3e4c0012a4d7f1",
      "channel": "WHATSAPP",
      "leadId": "651a0b2f4d9c1e0033b8e5a2"
    },
    {
      "id": "652f1b3e8b3e4c0012a4d802",
      "channel": "EMAIL",
      "leadId": "651a0b2f4d9c1e0033b8e5a2"
    }
  ],
  "meta": {
    "limit": 20,
    "count": 2,
    "total": 2,
    "page": 1,
    "totalPages": 1
  }
}

curl "https://api.gsengage.com/api/v1/conversations/threads/652f1a9c8b3e4c0012a4d7f1/messages?apiKey=SUA_CHAVE&limit=50&page=1"

{
  "data": [
    {
      "id": "6531c04a8b3e4c0012a4e910",
      "content": "Olá! Vi que você baixou nosso material. Posso ajudar?"
    },
    {
      "id": "6531c07d8b3e4c0012a4e922",
      "content": "Oi! Sim, queria entender os planos."
    }
  ],
  "meta": {
    "limit": 50,
    "count": 2,
    "total": 2,
    "page": 1,
    "totalPages": 1
  }
}

As duas chamadas usam a mesma paginação. Você controla o tamanho da página com limit e navega com page.

No bloco meta da resposta você tem tudo para saber se acabou:

A regra é: continue incrementando page enquanto page for menor que totalPages. Quando chegarem iguais, você leu tudo.

Este é o cenário mais comum: você quer que o histórico de conversas do GS Engage também apareça no seu CRM, num data warehouse ou num relatório. A lógica é sempre a mesma.

Um esqueleto em Python que amarra as duas chamadas:

import os
import requests

BASE = "https://api.gsengage.com/api/v1"
API_KEY = os.environ["GSENGAGE_API_KEY"]  # nunca escreva a chave no código

def get_pages(path):
    """Percorre todas as páginas de um endpoint paginado e devolve os itens."""
    page = 1
    while True:
        resp = requests.get(
            f"{BASE}{path}",
            params={"apiKey": API_KEY, "limit": 50, "page": page},
        )
        resp.raise_for_status()
        body = resp.json()
        for item in body["data"]:
            yield item
        meta = body["meta"]
        if meta["page"] >= meta["totalPages"]:
            break
        page += 1

# 1) Todas as conversas
for thread in get_pages("/conversations/threads"):
    # 2) Todas as mensagens de cada conversa
    for message in get_pages(f"/conversations/threads/{thread['id']}/messages"):
        # 3) Aqui você grava no seu sistema, vinculando ao lead
        salvar_no_seu_sistema(thread["leadId"], thread["channel"], message)

Se passar do teto, a API responde com 429 e alguns cabeçalhos que te dizem exatamente quanto esperar:

As mensagens de erro do GS Engage já vêm em português — leia-as com atenção, elas costumam dizer o que corrigir.

O corpo de um erro 400 segue o formato abaixo, apontando o campo problemático:

{
  "error": {
    "message": "Descrição do que deu errado.",
    "errors": [
      { "field": ["page"], "message": "Deve ser um número maior que zero." }
    ]
  }
}