Grupos

Os grupos do WhatsApp em que o número conectado participa aparecem no painel como conversas. Na API, um grupo também é uma conversa: o id do grupo é um contact_id. Com ele você:

• lê o histórico com GET /contacts/{contact_id}/messages;
• envia mensagens com POST /messages e { "contact_id": "<id do grupo>" };
• busca, arquiva ou atribui a conversa com os endpoints de Contatos (o contato do grupo tem is_group: true).

Grupos não são atendidos pelos agentes de IA.

O objeto grupo

{
  "id": "6fa72198-41f5-4c7f-8fc5-5c84c28e7e00",
  "object": "group",
  "name": "Equipe de Vendas",
  "jid": "120363012345678901@g.us",
  "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
  "unread_count": 3,
  "last_message_at": "2026-11-11T13:58:10Z",
  "last_message_preview": "Fechei mais 2 pedidos hoje 🎉",
  "archived_at": null,
  "created_at": "2026-04-01T12:00:00Z"
}

Campo	Tipo	Descrição
id	UUID	ID do grupo. É o contact_id da conversa do grupo: use para ler o histórico e enviar mensagens.
object	string	Sempre group.
name	string ou null	Nome do grupo no WhatsApp.
jid	string ou null	Identificador do grupo no WhatsApp (termina em @g.us).
channel_id	UUID ou null	Canal (número de WhatsApp) que participa do grupo.
unread_count	inteiro	Mensagens não lidas no painel.
last_message_at	data ou null	Data da última mensagem.
last_message_preview	string ou null	Prévia da última mensagem.
archived_at	data ou null	Quando a conversa do grupo foi arquivada (null = ativa).
created_at	data	Quando o grupo apareceu na TopTalking.

Listar grupos

GET/v1/groups

Lista os grupos que aparecem no painel, dos mais recentes para os mais antigos, com paginação. Use para descobrir o id de um grupo pelo nome antes de ler ou enviar mensagens.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
search	query	string	não	Parte do nome do grupo (até 100 caracteres).
channel_id	query	UUID	não	Só grupos deste canal.
limit	query	inteiro	não	Itens por página, 1 a 100 (padrão 20).
cursor	query	string	não	next_cursor da página anterior.

curl

curl "https://platform.toptalking.com.br/v1/groups?search=vendas" \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

JavaScript

const url = new URL('https://platform.toptalking.com.br/v1/groups');
url.searchParams.set('search', 'vendas');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});
const { data: grupos } = await res.json();
const grupoId = grupos[0]?.id; // use como contact_id

Python

import os
import requests

res = requests.get(
    "https://platform.toptalking.com.br/v1/groups",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    params={"search": "vendas"},
    timeout=30,
)
res.raise_for_status()
grupos = res.json()["data"]

Resposta 200

{
  "object": "list",
  "data": [
    {
      "id": "6fa72198-41f5-4c7f-8fc5-5c84c28e7e00",
      "object": "group",
      "name": "Equipe de Vendas",
      "jid": "120363012345678901@g.us",
      "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
      "unread_count": 3,
      "last_message_at": "2026-11-11T13:58:10Z",
      "last_message_preview": "Fechei mais 2 pedidos hoje 🎉",
      "archived_at": null,
      "created_at": "2026-04-01T12:00:00Z"
    },
    {
      "id": "8255ed43-3d44-4909-bc51-f7a9e810f214",
      "object": "group",
      "name": "Fornecedores - Vendas",
      "jid": "120363029876543210@g.us",
      "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
      "unread_count": 0,
      "last_message_at": "2026-11-08T17:22:05Z",
      "last_message_preview": "O lote de tênis chega na terça.",
      "archived_at": null,
      "created_at": "2026-05-12T09:40:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Erros

Só os gerais: 401 (chave) e 429 (limite por minuto). Veja Erros.

Participantes do grupo

GET/v1/groups/{group_id}/participants

Busca na hora, no WhatsApp conectado, quem está no grupo e quem é administrador. Por isso precisa do canal do grupo conectado — se ele estiver desconectado, a resposta é 422 channel_unavailable.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
group_id	caminho	UUID	sim	ID do grupo (o mesmo contact_id).

A lista vem inteira numa página (has_more: false).

curl

curl https://platform.toptalking.com.br/v1/groups/6fa72198-41f5-4c7f-8fc5-5c84c28e7e00/participants \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

JavaScript

const groupId = '6fa72198-41f5-4c7f-8fc5-5c84c28e7e00';
const res = await fetch(
  `https://platform.toptalking.com.br/v1/groups/${groupId}/participants`,
  { headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` } },
);
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const admins = body.data.filter((p) => p.role !== 'member');

Python

import os
import requests

group_id = "6fa72198-41f5-4c7f-8fc5-5c84c28e7e00"
res = requests.get(
    f"https://platform.toptalking.com.br/v1/groups/{group_id}/participants",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
participantes = res.json()["data"]

Resposta 200

{
  "object": "list",
  "data": [
    {
      "object": "group_participant",
      "phone": "5511988887777",
      "name": "Loja Aurora",
      "role": "superadmin",
      "avatar_url": "https://arquivos.exemplo.com/avatars/loja-aurora.jpg"
    },
    {
      "object": "group_participant",
      "phone": "5511991112222",
      "name": "Carla Mendes",
      "role": "admin",
      "avatar_url": null
    },
    {
      "object": "group_participant",
      "phone": "5521987654321",
      "name": "João Pereira",
      "role": "member",
      "avatar_url": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Campo	Tipo	Descrição
object	string	Sempre group_participant.
phone	string ou null	Telefone do participante, só dígitos com DDI.
name	string ou null	Nome do participante, quando conhecido.
role	string	member (participante), admin (administrador) ou superadmin (quem criou o grupo).
avatar_url	string ou null	Foto de perfil, quando disponível.

Erros

HTTP	code	Quando acontece
404	resource_not_found	O grupo não existe ou é de outra organização.
422	channel_unavailable	O WhatsApp do grupo está desconectado. Reconecte o canal e tente de novo.
502	provider_error	O WhatsApp não respondeu à consulta. Tente de novo em instantes.

422 channel_unavailable

{
  "error": {
    "type": "channel_error",
    "code": "channel_unavailable",
    "message": "WhatsApp desconectado. Reconecte no painel.",
    "request_id": "req_6f1d2c3b4a5e"
  }
}

Ler as mensagens do grupo

Use o id do grupo em GET /contacts/{contact_id}/messages. Em grupos, sender_name diz quem mandou cada mensagem recebida.

GET/v1/contacts/{contact_id}/messages

curl

curl "https://platform.toptalking.com.br/v1/contacts/6fa72198-41f5-4c7f-8fc5-5c84c28e7e00/messages?limit=20" \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

JavaScript

const groupId = '6fa72198-41f5-4c7f-8fc5-5c84c28e7e00';
const res = await fetch(
  `https://platform.toptalking.com.br/v1/contacts/${groupId}/messages?limit=20`,
  { headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` } },
);
const { data: mensagens } = await res.json();
for (const m of mensagens) console.log(`${m.sender_name ?? 'Nós'}: ${m.text}`);

Python

import os
import requests

group_id = "6fa72198-41f5-4c7f-8fc5-5c84c28e7e00"
res = requests.get(
    f"https://platform.toptalking.com.br/v1/contacts/{group_id}/messages",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    params={"limit": 20},
    timeout=30,
)
res.raise_for_status()
for m in res.json()["data"]:
    print(f"{m['sender_name'] or 'Nós'}: {m['text']}")

Resposta 200

{
  "object": "list",
  "data": [
    {
      "id": "cb42b3fb-9e83-46aa-b7f6-f3aca950abf5",
      "object": "message",
      "contact_id": "6fa72198-41f5-4c7f-8fc5-5c84c28e7e00",
      "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
      "direction": "inbound",
      "type": "text",
      "text": "Fechei mais 2 pedidos hoje 🎉",
      "media": null,
      "status": "delivered",
      "error": null,
      "reply_to_id": null,
      "reaction": null,
      "sender_name": "Carla Mendes",
      "transcript": null,
      "created_at": "2026-11-11T13:58:10Z",
      "edited_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMS0xMVQxMzo1ODoxMFoifQ"
}

Enviar mensagem para o grupo

Use POST /messages com o id do grupo em contact_id (to é só para telefones). Texto, mídia e respostas citando (reply_to_id) funcionam como numa conversa individual.

POST/v1/messages

curl

curl https://platform.toptalking.com.br/v1/messages \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: meta-diaria-2026-11-11" \
  -d '{
    "contact_id": "6fa72198-41f5-4c7f-8fc5-5c84c28e7e00",
    "text": "Bom dia, time! Meta de hoje: 15 pedidos. Bora! 💪"
  }'

JavaScript

const res = await fetch('https://platform.toptalking.com.br/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'meta-diaria-2026-11-11',
  },
  body: JSON.stringify({
    contact_id: '6fa72198-41f5-4c7f-8fc5-5c84c28e7e00', // id do grupo
    text: 'Bom dia, time! Meta de hoje: 15 pedidos. Bora! 💪',
  }),
});
const mensagem = await res.json();

Python

import os
import requests

res = requests.post(
    "https://platform.toptalking.com.br/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}",
        "Idempotency-Key": "meta-diaria-2026-11-11",
    },
    json={
        "contact_id": "6fa72198-41f5-4c7f-8fc5-5c84c28e7e00",  # id do grupo
        "text": "Bom dia, time! Meta de hoje: 15 pedidos. Bora! 💪",
    },
    timeout=30,
)
res.raise_for_status()
mensagem = res.json()

Resposta 201

{
  "id": "37e1fdb6-6cd4-4345-bbaa-58216b232122",
  "object": "message",
  "contact_id": "6fa72198-41f5-4c7f-8fc5-5c84c28e7e00",
  "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
  "direction": "outbound",
  "type": "text",
  "text": "Bom dia, time! Meta de hoje: 15 pedidos. Bora! 💪",
  "media": null,
  "status": "sent",
  "error": null,
  "reply_to_id": null,
  "reaction": null,
  "sender_name": null,
  "transcript": null,
  "created_at": "2026-11-11T11:00:03Z",
  "edited_at": null
}

Os erros são os de POST /messages. O mais comum em grupos é 422 channel_unavailable, quando o WhatsApp do grupo está desconectado.

Grupos também têm regras

Mensagens automáticas em grupos grandes, ou em grupos de pessoas que não esperam receber, podem levar a denúncias e ao banimento do número. Leia Boas práticas no WhatsApp.

Receber mensagens de grupos

Mensagens recebidas em grupos chegam no webhook message.received como as demais: data.contact.is_group é true, data.contact.id é o id do grupo e data.message.sender_name diz quem mandou.

Para listar só conversas de grupo (ou só individuais) junto com os demais filtros de contato, use GET /contacts?is_group=true.