Integração com o Gateway

Autenticação

Envie os cabeçalhos abaixo em todas as operações de atendimento. A credencial é fornecida pelo responsável pela instalação. O Gateway deve guardá-la no servidor e obter a organização e o usuário da sessão autenticada.

Authorization: Bearer <credencial-do-serviço>
X-Organization-Id: <organização-autorizada>
X-User-Id: <usuário-autenticado>
Content-Type: application/json
Accept: application/json

Os exemplos usam identidades fictícias. Use as organizações autorizadas na sua integração.

Operações

Abrir uma conversa com PHP

Gere e persista o identificador da conversa antes da chamada. Repetir a mesma solicitação com a mesma identidade recupera a conversa.

<?php
// Valores vindos da sessão autenticada do seu Gateway.
$organizationId = 'empresa-demo';
$userId = 'usuario-demo';
$baseUrl = 'https://ask-ia-agente.mogo.com.br';
$token = getenv('MOGO_SERVICE_TOKEN');
if (!$token) {
    throw new RuntimeException('Configure MOGO_SERVICE_TOKEN no servidor PHP.');
}

// Gere um UUID para a conversa e persista antes da primeira chamada.
$conversationId = 'c95f18a5-dde7-4299-867b-9a07f40a565b';
$request = curl_init($baseUrl . '/v1/conversations');
curl_setopt_array($request, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'X-Organization-Id: ' . $organizationId,
        'X-User-Id: ' . $userId,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'conversation_id' => $conversationId,
        'product' => 'mogo-gourmet',
        'establishment_id' => null,
    ], JSON_THROW_ON_ERROR),
]);
$body = curl_exec($request);
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
if ($body === false) {
    throw new RuntimeException('Não foi possível acessar o serviço.');
}
curl_close($request);
if (!in_array($status, [200, 201], true)) {
    throw new RuntimeException('O serviço retornou HTTP ' . $status);
}
$conversation = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

Enviar uma pergunta

Envie o JSON a POST /v1/conversations/{id}/messages. O identificador da mensagem deve ser um UUID persistido pelo Gateway. A sequência começa em 1. O campo context é opcional e, quando enviado, deve ser um objeto JSON. Pode conter version, screen e timezone.

{
  "message_id": "f3efb748-a758-444f-bdaa-ce669d85e2e7",
  "sequence": 1,
  "question": "Como consulto os pedidos do mês passado?",
  "context": {
    "timezone": "America/Sao_Paulo"
  }
}

Sem informações de contexto, omita o campo ou envie "context": {}. Enviar "context": [] retorna HTTP 422 com error.code: invalid_request.

Em PHP, converta o array associativo de contexto em objeto. Com o array vazio, (object) $context produz "context": {} no JSON.

$context = [];
$body = json_encode([
    'message_id' => $messageId,
    'sequence' => 1,
    'question' => 'Como consulto os pedidos do mês passado?',
    'context' => (object) $context,
], JSON_THROW_ON_ERROR);

Consulte GET /v1/conversations/{id}/messages/{message_id} com os mesmos cabeçalhos até receber o resultado.

{
  "conversation_id": "c95f18a5-dde7-4299-867b-9a07f40a565b",
  "message_id": "f3efb748-a758-444f-bdaa-ce669d85e2e7",
  "sequence": 1,
  "status": "needs_info",
  "source": "mogo_agent",
  "answer": "Você quer consultar pedidos de delivery, mesa ou comanda?"
}

Histórico e mensagens simultâneas

A conversa pertence à combinação de integração, organização e usuário. Cada pessoa pode abrir várias conversas. Mantenha uma mensagem em andamento por conversa e use a próxima sequência apenas depois que o turno anterior terminar. Abra outra conversa ao mudar de estabelecimento.

Reenvie a mesma mensagem com o mesmo identificador e conteúdo após um timeout. Uma nova pergunta recebe outro identificador. Conflitos de conteúdo, sequência ou mensagens simultâneas retornam HTTP 409. Uma tentativa de consultar a conversa de outra pessoa retorna HTTP 404.

Resultados e fallback

• queued e running indicam trabalho em andamento.
• answered contém a resposta pública em answer.
• needs_info contém uma pergunta de esclarecimento para a mesma conversa.
• insufficient_evidence contém o limite da investigação e pode exigir atendimento humano.
• unavailable indica indisponibilidade técnica e permite usar o fluxo alternativo do Gateway.

Falhas de conexão persistentes, timeouts de transporte e erros HTTP 502, 503 ou 504 podem acionar o fallback. Primeiro tente recuperar o estado pelo identificador original. Um HTTP 500 persistente também deve ser tratado como indisponibilidade. HTTP 429 com service_overloaded permite aguardar o tempo de Retry-After e recorrer ao fallback se a indisponibilidade ultrapassar o limite da chamada. quota_exceeded segue a política de uso da integração.

Resultados de esclarecimento e evidência insuficiente fazem parte do atendimento. Erros HTTP 400, 401, 403, 404, 409, 413 e 422 exigem tratamento da solicitação ou identidade.

Retomar após fallback

Persista a origem e o texto escolhidos antes de exibir a resposta. Ao recuperar a conexão, envie a mesma pergunta, contexto e sequência à rota PUT /v1/conversations/{id}/messages/{message_id}/fallback, acrescentando answer com o texto efetivamente exibido. A operação aceita repetição idêntica.

Se a conversa ainda não existir no serviço, repita primeiro sua criação com o identificador original. Sincronize os turnos pendentes em ordem antes da próxima pergunta. Ignore uma resposta tardia do agente depois que o Gateway escolher o fallback para aquele turno.