Atividades

Gerencie tarefas e atividades dentro do pipeline de vendas. Agende ligações, reuniões, emails e acompanhamentos com suporte a templates e sequências automatizadas.

Base URL

As rotas desta página usam o prefixo /api/v1/accounts/{account_id}/pipeline. Cada bloco abaixo mostra o caminho completo do recurso.

Todas pertencem ao módulo Pipeline Pro: numa conta em que ele está desligado a resposta é 403 com "code": "pipeline_board_disabled". Uma permissão negada também responde 403. Agentes só enxergam atividades de cards em pipelines dos quais são membros; um card fora desse alcance responde 404, igual a um card inexistente.

Listar Atividades

GET/api/v1/accounts/{account_id}/pipeline/activities

Lista atividades com filtros.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`pipeline_card_id`(query)	`integer`	Nao	Filtrar por card do pipeline
`type`(query)	`string`	Nao	call, email, meeting, task, note, demo, follow_up (filtra activity_type)
`status`(query)	`string`	Nao	Status: pending, in_progress, completed, cancelled
`priority`(query)	`string`	Nao	low, medium, high ou urgent
`assigned_to_id`(query)	`integer`	Nao	Filtrar por responsável
`overdue`(query)	`boolean`	Nao	true para apenas atividades atrasadas
`upcoming`(query)	`boolean`	Nao	true para apenas atividades futuras (ignorado quando overdue=true)
`page`(query)	`integer`	Nao	Página (padrão 1)
`per_page`(query)	`integer`	Nao	Itens por página (padrão 25, máximo 100)

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline/activities?status=pending" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Lista de atividades (chave activities), ordenada por scheduled_at crescente

json

{
  "activities": [
    {
      "id": 1,
      "pipeline_card_id": 5,
      "activity_type": "call",
      "status": "pending",
      "priority": "medium",
      "title": "Ligação de follow-up",
      "description": "Confirmar interesse na proposta",
      "scheduled_at": "2026-02-20T14:00:00Z",
      "due_at": null,
      "started_at": null,
      "completed_at": null,
      "cancelled_at": null,
      "duration": 30,
      "formatted_duration": "30min",
      "outcome": null,
      "outcome_notes": null,
      "value_impact": null,
      "score_impact": null,
      "is_automated": false,
      "source": "manual",
      "is_overdue": false,
      "metadata": {},
      "created_at": "2026-02-15T10:00:00Z",
      "updated_at": "2026-02-15T10:00:00Z",
      "created_by": { "id": 3, "name": "Maria Santos", "email": "maria@exemplo.com", "avatar_url": "https://..." },
      "assigned_to": { "id": 3, "name": "Maria Santos", "email": "maria@exemplo.com", "avatar_url": "https://..." }
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 15,
    "per_page": 25
  }
}

POST/api/v1/accounts/{account_id}/pipeline/activities

Cria uma nova atividade.

Parâmetro obrigatório na URL

O pipeline_card_id deve ser passado como query param na URL, não no corpo da requisição. Todos os campos do corpo devem estar dentro do wrapper activity.

Query Params

Nome	Tipo	Obrigatorio	Descricao
`pipeline_card_id`(query)	`integer`	Sim	ID do card do pipeline ao qual a atividade pertence

Body (dentro de activity)

Nome	Tipo	Obrigatorio	Descricao
`title`	`string`	Sim	Título da atividade (máximo 255 caracteres)
`activity_type`	`string`	Sim	call, email, meeting, task, note, demo, follow_up
`priority`	`string`	Nao	low, medium (padrão), high ou urgent
`status`	`string`	Nao	pending (padrão), in_progress, completed ou cancelled
`scheduled_at`	`string`	Nao	Data/hora agendada (ISO 8601)
`due_at`	`string`	Nao	Prazo (ISO 8601)
`duration`	`integer`	Nao	Duração em minutos (não negativa)
`description`	`string`	Nao	Descrição detalhada (máximo 5000 caracteres)
`assigned_to_id`	`integer`	Nao	ID do agente responsável (da mesma conta)
`contact_id`	`integer`	Nao	ID do contato associado (da mesma conta)
`conversation_id`	`integer`	Nao	ID da conversa associada (da mesma conta)
`metadata`	`object`	Nao	Dados livres da atividade

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/activities?pipeline_card_id=5" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "activity": {
      "activity_type": "meeting",
      "title": "Reuniao de apresentacao",
      "scheduled_at": "2026-02-20T14:00:00Z",
      "duration": 60
    }
  }'

Resposta e erros

Sucesso responde 201 com o mesmo objeto da listagem (sem wrapper). Falha de validação responde 422 com { "errors": ["..."] }. O autor é sempre o usuário autenticado; não é possível definir created_by.

Nota

Para GET, PATCH e DELETE em uma atividade específica, inclua ?pipeline_card_id=XXX na URL (card_id é aceito como sinônimo). A atividade é procurada dentro desse card; sem o parâmetro, ou com uma atividade de outro card, a resposta é 404. O mesmo vale para as ações abaixo.

GET/api/v1/accounts/{account_id}/pipeline/activities/{id}?pipeline_card_id={card_id}

Retorna detalhes de uma atividade: os campos da listagem mais contact, conversation_id, participants, attachments e reminders.

PATCH/api/v1/accounts/{account_id}/pipeline/activities/{id}?pipeline_card_id={card_id}

Atualiza uma atividade. Os campos vão dentro do objeto activity (os mesmos da criação). Responde 200 com a atividade; validação falha em 422 com { errors: [...] }. PUT é aceito como alias.

DELETE/api/v1/accounts/{account_id}/pipeline/activities/{id}?pipeline_card_id={card_id}

Remove uma atividade. Requer administrador. Responde 204 sem corpo.

Ações da Atividade

As quatro ações respondem 200 com a atividade atualizada. Quando o estado atual não permite a ação, a resposta é 422 com { "errors": [...] }. Os campos de corpo destas ações vão no topo, fora do wrapper activity.

POST/api/v1/accounts/{account_id}/pipeline/activities/{id}/start?pipeline_card_id={card_id}

Inicia a atividade (status in_progress e started_at). Atividade concluída ou cancelada retorna 422.

POST/api/v1/accounts/{account_id}/pipeline/activities/{id}/complete?pipeline_card_id={card_id}

Marca a atividade como concluída. Atividade cancelada retorna 422. Se a atividade foi iniciada, duration passa a ser o tempo desde started_at, em minutos.

Body

Nome	Tipo	Obrigatorio	Descricao
`outcome`	`string`	Nao	Resultado da atividade, validado conforme o tipo (ex.: successful, no_answer para call)
`outcome_notes`	`string`	Nao	Observações sobre o resultado
`value_impact`	`number`	Nao	Impacto no valor
`score_impact`	`integer`	Nao	Impacto no score

POST/api/v1/accounts/{account_id}/pipeline/activities/{id}/cancel?pipeline_card_id={card_id}

Cancela a atividade. Atividade concluída retorna 422.

Body

Nome	Tipo	Obrigatorio	Descricao
`reason`	`string`	Nao	Motivo do cancelamento; é gravado em outcome_notes

POST/api/v1/accounts/{account_id}/pipeline/activities/{id}/reschedule?pipeline_card_id={card_id}

Reagenda a atividade.

Body

Nome	Tipo	Obrigatorio	Descricao
`scheduled_at`	`string`	Sim	Nova data/hora (ISO 8601)

GET/api/v1/accounts/{account_id}/pipeline/activities/search

Busca atividades por texto no título e na descrição, com filtros. Responde no mesmo formato da listagem ({ activities, meta }), ordenado por scheduled_at decrescente.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`q`(query)	`string`	Nao	Texto de busca (sem ele, aplica apenas os filtros)
`type`(query)	`string`	Nao	Filtra activity_type
`status`(query)	`string`	Nao	Filtra status
`priority`(query)	`string`	Nao	Filtra prioridade
`assigned_to_id`(query)	`integer`	Nao	Filtra responsável
`pipeline_card_id`(query)	`integer`	Nao	Filtra por card
`date_from`(query)	`string`	Nao	Início da janela de scheduled_at. Só é aplicado junto com date_to
`date_to`(query)	`string`	Nao	Fim da janela de scheduled_at. Só é aplicado junto com date_from
`page`(query)	`integer`	Nao	Página (padrão 1)
`per_page`(query)	`integer`	Nao	Itens por página (padrão 25, máximo 100)

GET/api/v1/accounts/{account_id}/pipeline/activities/analytics

Métricas de atividades (conclusão, atrasos, por tipo), contando as atividades criadas no período.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`pipeline_card_id`(query)	`integer`	Nao	Restringe a um card. Sem ele, considera os cards visíveis ao usuário
`date_from`(query)	`string`	Nao	Data inicial (AAAA-MM-DD). Só vale junto com date_to
`date_to`(query)	`string`	Nao	Data final (AAAA-MM-DD). Sem as duas datas, ou com uma data ilegível, o período volta ao padrão: últimos 30 dias

200Analytics de atividades (objeto top-level, sem envelope data)

json

{
  "total": 150,
  "by_type": { "call": 45, "meeting": 30, "email": 50, "task": 25 },
  "by_status": { "pending": 40, "in_progress": 12, "completed": 98, "cancelled": 0 },
  "by_priority": { "low": 10, "medium": 100, "high": 40 },
  "completion_rate": 65.3,
  "overdue_count": 12,
  "upcoming_count": 20,
  "average_duration": 18,
  "by_outcome": { "successful": 80, "no_answer": 18 }
}

Operações em Lote

POST/api/v1/accounts/{account_id}/pipeline/activities/bulk_create

Cria a mesma atividade em múltiplos cards de uma vez (max 100 cards).

Body

Nome	Tipo	Obrigatorio	Descricao
`pipeline_card_ids`	`array`	Sim	IDs dos cards onde a atividade será criada (max 100). Mais que 100 retorna 400. Não é preciso enviar pipeline_card_id na query nesta rota.
`activity`	`object`	Sim	Objeto com os campos da atividade (activity_type, title, scheduled_at, etc.) — os mesmos de Criar Atividade.

Cards fora do alcance são descartados em silêncio

IDs de cards de outra conta, inexistentes ou em pipelines que o agente não vê são removidos da lista antes do processamento: não aparecem nem em created nem em failed. Compare success_count + failure_count com o total enviado para detectar IDs descartados.

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/activities/bulk_create" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_card_ids": [5, 9, 12],
    "activity": { "activity_type": "call", "title": "Ligacao de prospeccao" }
  }'

200Resultado por card. created traz as atividades no formato da listagem; failed traz o card e as mensagens de validação.

json

{
  "created": [ { "id": 41, "pipeline_card_id": 5, "activity_type": "call", "title": "Ligacao de prospeccao" } ],
  "failed": [ { "id": 12, "error": ["..."] } ],
  "success_count": 1,
  "failure_count": 1
}

POST/api/v1/accounts/{account_id}/pipeline/activities/create_from_template?pipeline_card_id={card_id}

Cria uma atividade a partir de um template da conta, vinculada ao card informado na query. Do template vêm activity_type, title (o nome do template), description (a descrição do template ou, na falta dela, default_content), duration e metadata; os campos de activity sobrescrevem esses valores. Cada uso incrementa usage_count do template. Responde 201 com a atividade; template inexistente responde 422 com { errors: ['Template not found'] }.

Query Params

Nome	Tipo	Obrigatorio	Descricao
`pipeline_card_id`(query)	`integer`	Sim	ID do card ao qual a atividade será vinculada

Body

Nome	Tipo	Obrigatorio	Descricao
`template_id`	`integer`	Sim	ID do template de atividade
`activity`	`object`	Nao	Campos da atividade que sobrescrevem os defaults do template

Sequências de Atividades

Uma definição descreve o gatilho e os passos reutilizáveis. Criar, atualizar, ativar ou desativar uma definição que contenha um passo de webhook exige um administrador da conta. Agentes podem gerenciar definições sem webhook.

GET/api/v1/accounts/{account_id}/pipeline/activity_sequences

Lista definições de sequências da conta.

Query Params

Nome	Tipo	Obrigatorio	Descricao
`active`(query)	`boolean`	Nao	Filtra por definições ativas (true) ou inativas (false)
`trigger_type`(query)	`string`	Nao	manual, stage_change, time_based ou condition_based
`page`(query)	`integer`	Nao	Página da listagem
`per_page`(query)	`integer`	Nao	Itens por página

POST/api/v1/accounts/{account_id}/pipeline/activity_sequences

Cria uma nova definição de sequência.

Body (pipeline_activity_sequence)

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Sim	Nome único da sequência na conta (máximo 255 caracteres)
`description`	`string`	Nao	Descrição
`trigger_type`	`string`	Nao	manual (padrão), stage_change, time_based ou condition_based
`trigger_conditions`	`object`	Nao	Condições compatíveis com trigger_type; use os formatos validados abaixo
`active`	`boolean`	Nao	Cria a definição ativa; padrão true
`steps`	`array`	Sim	Lista não vazia de objetos. Cada passo exige activity_type e title; atrasos usam delay_days/delay_hours

Contratos de trigger_conditions

manual: objeto vazio {}.
stage_change: { "funnel_id": 9, "from_stage_id": "lead", "to_stage_id": "qualified" }. to_stage_id é obrigatório; os demais são opcionais.
time_based: exatamente uma cadência, { "every_n_days": 7 } (1 a 365) ou { "cron_expression": "0 9 * * 1" }.
condition_based: { "field": "lead_score", "operator": ">=", "value": 80 }.

O cron aceita exatamente cinco campos numéricos: minuto (0-59), hora (0-23), dia do mês (1-31), mês (1-12) e dia da semana (0-7). São aceitos *, */n, listas e intervalos crescentes; nomes e um campo de segundos retornam 422.

Campos dos passos

Tipos aceitos: call, email, meeting,task, note, demo, follow_up,delay, webhook, whatsapp_message ewhatsapp_media. Além de activity_type etitle, os campos gerais incluem step_number,description, delay_days, delay_hours,duration, priority, assign_to,schedule_hours, due_days e on_failure.

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/activity_sequences" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_activity_sequence": {
      "name": "Cadencia de Vendas",
      "trigger_type": "time_based",
      "trigger_conditions": { "cron_expression": "0 9 * * 1-5" },
      "steps": [
        { "step_number": 1, "activity_type": "call", "title": "Ligacao inicial", "delay_days": 0, "duration": 15 },
        { "step_number": 2, "activity_type": "email", "title": "Email de follow-up", "delay_days": 2, "duration": 5 }
      ]
    }
  }'

201Definição criada

json

{
  "data": {
    "id": 3,
    "name": "Cadência de Vendas",
    "trigger_type": "time_based",
    "trigger_conditions": { "cron_expression": "0 9 * * 1-5" },
    "active": true,
    "step_count": 2,
    "steps": [
      { "step_number": 1, "activity_type": "call", "title": "Ligação inicial", "delay_days": 0, "duration": 15 }
    ]
  },
  "message": "Activity sequence created successfully"
}

GET/api/v1/accounts/{account_id}/pipeline/activity_sequences/{id}

Retorna a definição e os totais de execuções.

PATCH/api/v1/accounts/{account_id}/pipeline/activity_sequences/{id}

Atualiza parcialmente a definição usando o wrapper pipeline_activity_sequence.

Execuções ativas e webhooks

Substituir steps retorna 422 enquanto houver execuções ativas. Se a definição atual ou a nova lista de passos contiver webhook, qualquer atualização exige administrador.

POST/api/v1/accounts/{account_id}/pipeline/activity_sequences/{id}/activate

Ativa a definição. Definições com webhook exigem administrador.

POST/api/v1/accounts/{account_id}/pipeline/activity_sequences/{id}/deactivate

Desativa a definição e pausa suas execuções ativas. Definições com webhook exigem administrador.

DELETE/api/v1/accounts/{account_id}/pipeline/activity_sequences/{id}

Remove uma definição sem execuções ativas. Requer administrador.

POST/api/v1/accounts/{account_id}/pipeline/activity_sequences/{id}/duplicate

Duplica a definição. A cópia nasce inativa, com o nome enviado em name ou 'Copy of <nome>'. Exige administrador ou pipeline_manage; se a definição tiver passos de webhook, exige administrador. Retorna 201 com { data, message }; falha retorna 422 com { error, details }.

GET/api/v1/accounts/{account_id}/pipeline/activity_sequences/webhook_credentials

Credenciais de webhook das sequências da conta (somente administrador; resposta com Cache-Control: no-store). Campos: inbound_configured, inbound_url (/webhooks/sequence-trigger/<token>), inbound_secret, inbound_signature_version, inbound_replay_protection_enabled, outbound_configured, outbound_signing_secret, authentication_window_seconds. 503 se a configuração de assinatura for inválida.

POST/api/v1/accounts/{account_id}/pipeline/activity_sequences/rotate_webhook_credentials

Rotaciona as credenciais (somente administrador). credential_scope: inbound, outbound ou all (padrão all); outro valor retorna 422. Retorna o mesmo formato de webhook_credentials; falha ao registrar a rotação retorna 503.

Templates de Atividade

Administradores e agentes leem os templates. Criar, atualizar e duplicar exige administrador ou agente com a permissão pipeline_manage; remover exige administrador. Uma permissão negada responde 403; um template de outra conta ou inexistente responde 404.

GET/api/v1/accounts/{account_id}/pipeline/activity_templates

Lista templates de atividade da conta, do mais recente para o mais antigo, com paginação.

Query Params

Nome	Tipo	Obrigatorio	Descricao
`active`(query)	`boolean`	Nao	true apenas ativos, false apenas inativos; omitido lista todos
`activity_type`(query)	`string`	Nao	Filtra por tipo
`category`(query)	`string`	Nao	Filtra por categoria
`sort`(query)	`string`	Nao	most_used ordena por usage_count decrescente
`page`(query)	`integer`	Nao	Página (padrão 1)
`per_page`(query)	`integer`	Nao	Itens por página (padrão 25, máximo 100)

200Templates (chaves data e meta)

json

{
  "data": [
    {
      "id": 4,
      "name": "Product Demo",
      "description": "Product demonstration meeting",
      "activity_type": "meeting",
      "category": "sales",
      "default_content": "Live demonstration of product features and capabilities.",
      "default_duration": 60,
      "default_metadata": { "demo_sections": ["Overview", "Key features"] },
      "active": true,
      "usage_count": 12,
      "created_at": "2026-08-01T12:00:00.000Z",
      "updated_at": "2026-09-20T15:10:00.000Z"
    }
  ],
  "meta": { "total": 1, "current_page": 1, "total_pages": 1, "per_page": 25 }
}

GET/api/v1/accounts/{account_id}/pipeline/activities/templates

Atalho usado para escolher um template ao criar uma atividade: lista só os templates ativos, ordenados por usage_count decrescente, sem paginação. A resposta é um array direto (sem data/meta) e cada item traz id, name, activity_type, category, description, default_content, default_duration, default_metadata e usage_count.

Query Params

Nome	Tipo	Obrigatorio	Descricao
`category`(query)	`string`	Nao	Filtra por categoria
`activity_type`(query)	`string`	Nao	Filtra por tipo

GET/api/v1/accounts/{account_id}/pipeline/activity_templates/{id}

Retorna um template.

200Template (chave data), com stats

json

{
  "data": {
    "id": 4,
    "name": "Product Demo",
    "description": "Product demonstration meeting",
    "activity_type": "meeting",
    "category": "sales",
    "default_content": "Live demonstration of product features and capabilities.",
    "default_duration": 60,
    "default_metadata": {},
    "active": true,
    "usage_count": 12,
    "created_at": "2026-08-01T12:00:00.000Z",
    "updated_at": "2026-09-20T15:10:00.000Z",
    "stats": { "total_uses": 12, "last_used_at": "2026-09-20T15:10:00.000Z" }
  }
}

Sobre stats

stats.total_uses repete usage_count, e stats.last_used_at é o updated_at do template — qualquer edição também o altera, então ele não é uma data de uso confiável.

POST/api/v1/accounts/{account_id}/pipeline/activity_templates

Cria um novo template.

Body (pipeline_activity_template)

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Sim	Nome do template (máximo 255 caracteres). Ao criar uma atividade pelo template, vira o title da atividade
`activity_type`	`string`	Sim	call, email, meeting, task, note, demo, follow_up
`category`	`string`	Nao	sales, support, onboarding, follow_up ou customer_success
`default_content`	`string`	Nao	Conteúdo padrão da atividade (não existe campo "title" no template)
`description`	`string`	Nao	Descrição padrão
`default_duration`	`integer`	Nao	Duração padrão em minutos (não negativa)
`default_metadata`	`object`	Nao	Metadados copiados para a atividade criada
`active`	`boolean`	Nao	Padrão true

Formato de resposta

Sucesso responde 201 com { "data": { ... }, "message": "Activity template created successfully" }, sem stats. Validação falha em 422 com { "error": "Failed to create activity template", "details": ["..."] }.

PATCH/api/v1/accounts/{account_id}/pipeline/activity_templates/{id}

Atualiza parcialmente um template. Aceita os mesmos campos da criação, dentro de pipeline_activity_template. Responde 200 com { data, message }; validação falha em 422 com { error, details }. PUT é aceito como alias.

bash

curl -X PATCH "https://chat.seudominio.com/api/v1/accounts/1/pipeline/activity_templates/4" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "pipeline_activity_template": { "default_duration": 45, "active": false } }'

POST/api/v1/accounts/{account_id}/pipeline/activity_templates/{id}/duplicate

Cria uma cópia do template com usage_count zerado. Responde 201 com { data, message }.

Body

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Nao	Nome da cópia, no topo do corpo. Padrão: "Copy of " + nome original. Nome inválido responde 422

DELETE/api/v1/accounts/{account_id}/pipeline/activity_templates/{id}

Remove um template. Requer administrador. Responde 200 com { message }.