Equipe

Os membros são as pessoas da equipe que usam o painel: donos, administradores e atendentes. Pela API você lista a equipe e usa o id de cada membro para atribuir conversas (assigned_to) e para filtrar as conversas de cada atendente.

Convidar, remover e mudar o papel de membros é feito no painel.

O objeto membro

{
  "id": "4083deb8-f96e-4093-8598-ebdd4dee786b",
  "object": "member",
  "name": "Carla Mendes",
  "email": "carla@lojaaurora.com.br",
  "role": "agent",
  "avatar_url": "https://arquivos.exemplo.com/avatars/carla.jpg",
  "joined_at": "2026-03-10T13:00:00Z"
}

Campo	Tipo	Descrição
id	UUID	ID do usuário. Use em assigned_to para atribuir conversas.
object	string	Sempre member.
name	string ou null	Nome da pessoa.
email	string ou null	E-mail de login.
role	string	owner (dono da conta), admin (administrador) ou agent (atendente).
avatar_url	string ou null	Foto de perfil.
joined_at	data	Quando entrou na organização.

Listar membros

GET/v1/members

Todos os membros da organização. Use para montar um seletor de responsável ou para descobrir o id de um atendente pelo nome ou e-mail.

Não tem parâmetros. A lista vem inteira numa página (has_more: false).

curl

curl https://platform.toptalking.com.br/v1/members \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

JavaScript

const res = await fetch('https://platform.toptalking.com.br/v1/members', {
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});
const { data: equipe } = await res.json();
const carla = equipe.find((m) => m.email === 'carla@lojaaurora.com.br');

Python

import os
import requests

res = requests.get(
    "https://platform.toptalking.com.br/v1/members",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
equipe = res.json()["data"]
carla = next(m for m in equipe if m["email"] == "carla@lojaaurora.com.br")

Resposta 200

{
  "object": "list",
  "data": [
    {
      "id": "4ce0bb29-e6f6-4a78-8d63-747e73e00071",
      "object": "member",
      "name": "Rafael Costa",
      "email": "rafael@lojaaurora.com.br",
      "role": "owner",
      "avatar_url": "https://arquivos.exemplo.com/avatars/rafael.jpg",
      "joined_at": "2026-02-10T12:00:00Z"
    },
    {
      "id": "384d33f5-953e-4d07-a85e-69e67e1bf89c",
      "object": "member",
      "name": "Bruno Alves",
      "email": "bruno@lojaaurora.com.br",
      "role": "admin",
      "avatar_url": null,
      "joined_at": "2026-02-15T18:30:00Z"
    },
    {
      "id": "4083deb8-f96e-4093-8598-ebdd4dee786b",
      "object": "member",
      "name": "Carla Mendes",
      "email": "carla@lojaaurora.com.br",
      "role": "agent",
      "avatar_url": "https://arquivos.exemplo.com/avatars/carla.jpg",
      "joined_at": "2026-03-10T13:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Erros

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

Buscar membro

GET/v1/members/{member_id}

Um membro pelo ID. Útil para mostrar o nome do responsável de uma conversa a partir do assigned_to do contato.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
member_id	caminho	UUID	sim	ID do membro (o mesmo valor de assigned_to).

curl

curl https://platform.toptalking.com.br/v1/members/4083deb8-f96e-4093-8598-ebdd4dee786b \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

JavaScript

const memberId = '4083deb8-f96e-4093-8598-ebdd4dee786b';
const res = await fetch(`https://platform.toptalking.com.br/v1/members/${memberId}`, {
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});
const membro = await res.json();
console.log(`Responsável: ${membro.name}`);

Python

import os
import requests

member_id = "4083deb8-f96e-4093-8598-ebdd4dee786b"
res = requests.get(
    f"https://platform.toptalking.com.br/v1/members/{member_id}",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
membro = res.json()

Resposta 200

{
  "id": "4083deb8-f96e-4093-8598-ebdd4dee786b",
  "object": "member",
  "name": "Carla Mendes",
  "email": "carla@lojaaurora.com.br",
  "role": "agent",
  "avatar_url": "https://arquivos.exemplo.com/avatars/carla.jpg",
  "joined_at": "2026-03-10T13:00:00Z"
}

Erros

HTTP	code	Quando acontece
404	resource_not_found	Não há membro com esse ID nesta organização (ex.: a pessoa saiu da equipe).

Atribuir uma conversa

Para definir o responsável por uma conversa, envie o id do membro em assigned_to com PATCH /contacts/{contact_id}. A conversa passa a aparecer para ele no painel como “minha”.

PATCH/v1/contacts/{contact_id}

Corpo	Efeito
{ "assigned_to": "<id do membro>" }	Atribui a conversa a este membro.
{ "assigned_to": null }	Libera a conversa (fica sem responsável).

curl

curl -X PATCH https://platform.toptalking.com.br/v1/contacts/3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60 \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "assigned_to": "4083deb8-f96e-4093-8598-ebdd4dee786b" }'

JavaScript

async function atribuir(contactId, memberId) {
  const res = await fetch(`https://platform.toptalking.com.br/v1/contacts/${contactId}`, {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ assigned_to: memberId }), // null libera a conversa
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body;
}

await atribuir('3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60', '4083deb8-f96e-4093-8598-ebdd4dee786b');

Python

import os
import requests

contact_id = "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60"
res = requests.patch(
    f"https://platform.toptalking.com.br/v1/contacts/{contact_id}",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    json={"assigned_to": "4083deb8-f96e-4093-8598-ebdd4dee786b"},  # None libera
    timeout=30,
)
res.raise_for_status()
contato = res.json()

A resposta 200 é o contato atualizado, com o novo assigned_to. A atribuição fica registrada no histórico de atribuições da conversa no painel e dispara o webhook contact.updated com assigned_to em changed_fields.

HTTP	code	Quando acontece
400	invalid_field	assigned_to não é um membro da organização (param: "assigned_to").
403	read_only_key	Chave somente leitura.
404	resource_not_found	O contato não existe.

400 invalid_field

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_field",
    "message": "Este usuário não é membro da organização. Veja GET /v1/members.",
    "param": "assigned_to",
    "request_id": "req_6f1d2c3b4a5e"
  }
}

Conversas de cada atendente

Filtre GET /contacts por assigned_to:

• ?assigned_to=<id do membro> — as conversas de um atendente;
• ?assigned_to=none — as conversas sem responsável (ótimo para distribuir a fila).

curl

# Conversas ativas sem responsável
curl "https://platform.toptalking.com.br/v1/contacts?assigned_to=none&archived=false&is_group=false" \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

JavaScript

// Distribui as conversas sem responsável entre os atendentes (rodízio simples)
const API = 'https://platform.toptalking.com.br/v1';
const headers = {
  Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}`,
  'Content-Type': 'application/json',
};

const { data: equipe } = await (await fetch(`${API}/members`, { headers })).json();
const atendentes = equipe.filter((m) => m.role === 'agent');

const url = `${API}/contacts?assigned_to=none&archived=false&is_group=false&limit=50`;
const { data: fila } = await (await fetch(url, { headers })).json();

for (const [i, contato] of fila.entries()) {
  const responsavel = atendentes[i % atendentes.length];
  await fetch(`${API}/contacts/${contato.id}`, {
    method: 'PATCH',
    headers,
    body: JSON.stringify({ assigned_to: responsavel.id }),
  });
}

Python

import os
import requests

res = requests.get(
    "https://platform.toptalking.com.br/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    params={"assigned_to": "none", "archived": "false", "is_group": "false"},
    timeout=30,
)
res.raise_for_status()
sem_responsavel = res.json()["data"]