Pular para o conteúdo
Conversas

Iniciar conversa com um contato

v1.0.0
POSThttps://api.growthaisystem.com/api/v1/conversations
  • ExigeAuthorization: Bearer gos_…— Chave de API (gos_…)· escoposconversations.writeconversations.outbound

Aborda um contato do CRM pelo WhatsApp: abre a conversa dele NO número escolhido (ou reencontra a que já existe) e manda a primeira mensagem, numa operação só — se o envio falha, nenhuma conversa vazia fica para trás.

  • Número por QR: text livre.
  • Número oficial da Meta: template (liste os aprovados em GET /whatsapp/templates). Texto livre só sai se o contato escreveu nas últimas 24h; quem nunca escreveu nunca tem janela (422 messaging_window_closed).

O destino é o telefone do cadastro (ou a identidade de WhatsApp já aprendida do contato). Se o contato já tem conversa nesse número e ela está com alguém do time (ai.paused), nada sai (409 conversation_paused). Contato com “não perturbe” = 422 send_rejected. A mensagem aparece como Integração (actor: "api") e dispara message.sent.

Escopos: conversations.write e conversations.outbound. Use `Idempotency-Key`: o retry com a mesma chave e o mesmo corpo devolve o mesmo resultado sem mandar de novo.

Funcionário digital: o pedido fica para o dono aprovar (202, acompanhe em GET /actions/{id}); na aprovação as mesmas regras são conferidas de novo e, se algo mudou (alguém assumiu a conversa, falou com o contato, o contato foi para a Lixeira), nada sai.

Corpo da requisição

application/jsonobrigatório

V1ConversationStartInputInput

  • contactIdstringobrigatório
    • tamanho 1–80
  • connectionIdstringobrigatório
    • tamanho 1–80
  • textstringopcional
    • tamanho 1–4096
    • namestringobrigatório
      • tamanho 1–512
    • languagestringobrigatório
      • tamanho 1–16
    • variablesstring[]opcional
      • padrão []
      • itens máx. 10

Respostas

14 respostas documentadas — o código, o que ele significa nesta rota e a forma do corpo.

200Deu certoapplication/json

A Idempotency-Key repetiu um início anterior: devolve a MESMA conversa e mensagem, com idempotency_replay: true. Nada saiu de novo.

V1ConversationStarted

    • idstring
    • channelstring
    • connectionIdstring | null
    • contactIdstring | null
      • idstring
      • namestring
      • phonestring | null
      • emailstring | null
    • contactDisplaystring | null
    • contactPhonestring | null
    • assignedUserIdstring | null
    • humanAssignedboolean
    • assignedAtstring | null
    • lastMessageAtstring | null
    • lastMessageDirectionstring | null
      • um de"inbound""outbound"
    • lastMessageActorstring | null
      • um de"user""contact""ia""automation""system""api""unknown"
    • archivedboolean
      • pausedboolean
      • pausedUntilstring | null
      • pausedReasonstring | null
      • appliesboolean
      • openboolean
      • expiresAtstring | null
    • createdAtstring
    • updatedAtstring
    • idstring
    • conversationIdstring
    • contactIdstring | null
    • channelstring
    • connectionIdstring | null
    • directionstring
      • um de"inbound""outbound"
    • actorstring
      • um de"user""contact""ia""automation""system""api""unknown"
    • userIdstring | null
    • typestring
    • textstring | null
    • transcriptionstring | null
    • transcriptionStatusstring | null
    • mediaTypestring | null
    • hasMediaboolean
    • statusstring
    • statusReasonstring | null
    • providerTimestampstring
    • createdAtstring
    • deletedAtstring | null
  • createdboolean
  • idempotency_replaytruepode faltar
    • sempre true