EntrarTeste grátis

API · Atualizado em 12/10/2026

Contexto do contato e sessões do bot pela API

Leia e grave variáveis do bot em um contato, mude o bloco em que ele está e encontre quem ficou preso na conversa automática, sem ticket.

Neste artigo
  1. Quando usar
  2. Pré-requisitos
  3. Rotas
  4. Passo a passo: gravar uma variável
  5. Mover o contato de bloco
  6. Achar quem está preso no bot
  7. Resultado esperado
  8. Problemas comuns
  9. Boas práticas
  10. Próximos passos
  11. Perguntas frequentes

Enquanto um contato conversa só com o bot, não existe ticket. Mesmo assim, o fluxo guarda variáveis e a posição do contato. A API permite ler e gravar essas variáveis, mover o contato de bloco e achar quem está preso no bot.

Quando usar

  • Para entregar ao bot dados do seu sistema antes de ele falar, como número do pedido ou nome do plano.
  • Para ler o que o bot coletou, como a opção escolhida, e usar no seu sistema.
  • Para destravar um contato que ficou no bot, devolvendo-o ao início ou a um bloco específico.
  • Para listar contatos há muito tempo em atendimento automático e passá-los a um atendente.

Pré-requisitos

  • contatos:ler para ler variáveis e conversas:ler para listar sessões.
  • contexto:escrever para gravar, apagar e mover de bloco. Esse escopo muda o comportamento do bot e não vem na chave padrão: crie a chave com Compatível com a Blip.
  • O contato precisa já ter conversado com o bot do fluxo. Caso contrário, a resposta é 404 bot_context_not_found.

Rotas

MétodoRotaEscopoO que faz
GET/v1/contacts/:id/contextcontatos:lerLista as variáveis do contato (com values=true, traz os valores)
GET/v1/contacts/:id/context/:namecontatos:lerLê uma variável
PUT/v1/contacts/:id/context/:namecontexto:escreverGrava uma variável
DELETE/v1/contacts/:id/context/:namecontexto:escreverApaga uma variável
PUT/v1/contacts/:id/bot-statecontexto:escreverMove o contato para um bloco ou para o início
GET/v1/bot-sessionsconversas:lerLista contatos em atendimento automático, sem ticket
GET/v1/contacts/:id/bot-sessionconversas:lerLê a sessão ativa de um contato, ou 404

As rotas de contexto atuam sobre a última execução do contato em um fluxo: o da chave ou o informado em ?flowId=. Uma chave de fluxo só pode nomear o próprio fluxo.

Passo a passo: gravar uma variável

  1. Grave o valor. value aceita texto, número ou booleano, até 64 KB. expirationSeconds é opcional, de 1 a 31536000:
curl -s -X PUT https://http.pipebr.app/v1/contacts/b3a1c9de-0000-4000-8000-000000000010/context/numero_pedido \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"value": "1234", "expirationSeconds": 86400}'
  1. A resposta confirma o fluxo e o nome:
{
  "contactId": "b3a1c9de-0000-4000-8000-000000000010",
  "flowId": "b3a1c9de-0000-4000-8000-0000000000f1",
  "name": "numero_pedido"
}
  1. Leia de volta quando precisar:
curl -s "https://http.pipebr.app/v1/contacts/b3a1c9de-0000-4000-8000-000000000010/context?values=true" \
  -H "Authorization: Bearer $PIPE_CHAVE"
{
  "contactId": "b3a1c9de-0000-4000-8000-000000000010",
  "flowId": "b3a1c9de-0000-4000-8000-0000000000f1",
  "total": 1,
  "data": [ { "name": "numero_pedido", "value": "1234" } ]
}

O nome da variável tem de 1 a 200 caracteres. Nomes reservados do motor dão 422 variable_reserved. O valor gravado não aparece nos registros de auditoria.

Mover o contato de bloco

Para devolver o contato ao início do fluxo, envie stateId: null. Para levá-lo a um bloco, informe o código do bloco:

curl -s -X PUT https://http.pipebr.app/v1/contacts/b3a1c9de-0000-4000-8000-000000000010/bot-state \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"stateId": null}'

A próxima mensagem do contato cai nesse bloco. Se o fluxo não tiver um bloco com o código informado, a resposta é 422 state_not_found. O campo flowId é opcional para chave de fluxo.

Achar quem está preso no bot

GET /v1/bot-sessions lista as execuções ativas do bot de contatos que não têm ticket. Filtros: flowId, contactId, state_id, idle_minutes_gte (minutos parado), limit e cursor.

curl -s "https://http.pipebr.app/v1/bot-sessions?idle_minutes_gte=30" \
  -H "Authorization: Bearer $PIPE_CHAVE"
{
  "data": [
    {
      "executionId": "b3a1c9de-0000-4000-8000-000000000600",
      "contactId": "b3a1c9de-0000-4000-8000-000000000010",
      "contactName": "Maria Exemplo",
      "contactPhone": "+5511955550101",
      "flowId": "b3a1c9de-0000-4000-8000-0000000000f1",
      "flowName": "Atendimento Girassol",
      "stateId": "menu-principal",
      "stateName": "Menu principal",
      "startedAt": "2026-10-12T13:00:00.000Z",
      "lastInboundAt": "2026-10-12T13:05:00.000Z",
      "lastOutboundAt": "2026-10-12T13:05:02.000Z",
      "hasActiveTicket": false
    }
  ],
  "page_info": { "has_next_page": false, "end_cursor": null }
}

Para tirar o contato do bot e levá-lo a uma pessoa, abra um ticket para ele. Veja Conversas e tickets.

Resultado esperado

O bot passa a enxergar as variáveis que você gravou, o contato volta a andar quando você o move de bloco, e sua rotina consegue achar sessões paradas e encaminhá-las.

Problemas comuns

  • 404 bot_context_not_found: o contato ainda não conversou com o bot daquele fluxo, então não há contexto.
  • 403 without_scope ao gravar: a chave não tem contexto:escrever. Crie uma chave com a opção Compatível com a Blip.
  • 422 variable_reserved: o nome pertence ao motor. Use um nome seu, como numero_pedido.
  • Contato não aparece em /v1/bot-sessions: se ele tem ticket ativo, não é uma sessão presa. Sessões listadas são só as sem ticket.

Boas práticas

  • Dê às variáveis nomes estáveis, em minúsculas e sem espaços, e use os mesmos nomes no fluxo (veja Variáveis do fluxo).
  • Use expirationSeconds para dados que perdem a validade, como um código temporário.
  • Teste o fluxo no painel de teste antes de mover contatos reais de bloco. Veja Como testar um fluxo.

Próximos passos

Perguntas frequentes

O que é o contexto do contato?

São as variáveis que o fluxo guarda para aquele contato na conversa com o bot, como nome, pedido ou opção escolhida. A API lê e grava essas variáveis.

Para que serve a sessão do bot?

Conversa só com o bot não é ticket. A rota de sessões lista quem está em atendimento automático, há quanto tempo e em que bloco, para você achar contatos presos.

Posso mudar o bloco em que o contato está?

Sim, com PUT /v1/contacts/:id/bot-state. Você escolhe o bloco ou devolve o contato para o início do fluxo. A próxima mensagem do contato cai nesse bloco.

Que variáveis a API não deixa gravar?

As reservadas do motor: nomes que começam com # ou com pipe., desk_, stateid@, previous-stateid@, currentflowsession@, e a variável Master-State. A resposta é 422 variable_reserved.