A API de um chatbot no Serprobots

Todo chatbot publicado através Serprobots possui uma API REST de conversação utilizada pela própria janela do canal web, mas que também pode ser utilizada por outros sistemas externos para se integrar com esse chatbot. Abaixo são descritos as principais operações dessa API.

Endpoint de criação da conversa

É o endpoint que cria a conversa, gerando um identificador que será usado nas trocas de mensagens daquela sessão.

POST https://serprobots.estaleiro.serpro.gov.br/web/<IDENTIFICADOR CHATBOT>/api/conversation/

Exemplo de chamada:

curl -X POST 'https://serprobots.estaleiro.serpro.gov.br/web/bot-supai-d/api/conversation/'

Retorno será um texto informando o Identificador Único (UUID) da conversa criada (conversationId). Exemplo:

8d19ef24-7433-4262-b9a8-170780723ac7

Endpoint de conversação

É o endpoint que manda uma mensagem para o chatbot e recebe de volta as respostas que o chatbot gerou para aquela pergunta.

POST https://serprobots.estaleiro.serpro.gov.br/web/<IDENTIFICADOR CHATBOT>/api/answer/

Exemplo de chamada:

curl -X POST 'https://serprobots.estaleiro.serpro.gov.br/web/bot-supai-d/api/answer/'\
    -H 'content-type: application/json'\
    --data-raw '{"parameters":{},"conversationId":"de7331b7-9076-4d8f-b473-0e4ca1095b11","text":"olá"}'

O payload enviado é um JSON informando o valor do 'conversationId' e o texto desejado '(text)':

{
    "parameters": {},
    "conversationId": "de7331b7-9076-4d8f-b473-0e4ca1095b11",
    "text": "olá"
}

O retorno será um JSON com com um array de respostas (campo contents), já que a resposta pode se tratar de várias partes, ou balões:

{
    "contents": [
        {
            "text": "Olha 👀 que coisa mais linda mais cheia de graça ♫ ♩",
            "type": "TEXT"
        }
    ],
    "conversationId": "de7331b7-9076-4d8f-b473-0e4ca1095b11",
    "empty": false,
    "question": "olá",
    "ui": {
    }
}

Uma resposta no array contents pode ser do tipo TEXT

{
    "type": "TEXT",
    "text": "Infelizmente não sei responder..."    
}

Há ainda respostas do tipo IMAGE, e nesse caso vai conter a URL da imagem:

{
    "type": "IMAGE",
    "url": "http://url.da/figura.png"    
}

Também existem respostas do tipo OPTIONS, que contém um título (title) seguido das opções (array options) que o usuário poderá escolher. Cada opção poderá ter um 'label' (valor visível para ser clicado) e um value (valor de fato enviado ao clicar na opção). Já o campo display vai sugerir uma forma de exibição dessas opções, podendo ser button, selection ou dropdown.

{
    "type": "OPTIONS"
    "title": "Você está bem?"
    "display": "button"
    "options": [
        {
            "label": "Sim",
            "showValue": true,
            "value": "yes"
        },
        {
            "label": "Não",
            "showValue": true,
            "value": "no"
        }        
    ]    
}

Existem ainda respostas o tipo FILE, que contém informações de um arquivo, sendo elas o nome desejado para o arquivo (fileName), o tamanho do arquivo em bytes (fileSize), o endereço para download do arquivo (url) e a descrição do arquivo (description).

{
    "type": "FILE",
    "fileName": "relatorio.pdf",
    "fileSize": 1023,            
    "url": "https://endereco.do/arquivo_b3ca6868-9eca.pdf",
    "description": "Aqui está o relatório solicitado."
}

Endpoint de Histórico de Mensagens

É o endpoint que recupera todas as mensagens de uma determinada conversa.

GET https://serprobots.estaleiro.serpro.gov.br/web/<IDENTIFICADOR CHATBOT>/api/conversation/<IDENTIFICADOR DA CONVERSA>/messages

Exemplo de chamada:

curl https://serprobots.estaleiro.serpro.gov.br/web/bot-teste-p/api/conversation/4e42069c-6149-4dd2-90a5-47c13cfa4b67/messages

O retorno é um JSON Array contendo todos os objetos respondidos anteriormente em ordem cronológica. Em cada objeto retornado, a pergunta feita pelo usuário vai constar no campo question e os balões de resposta estarão no campo contents, seguindo a sintaxe dos tipos de respostas explicadas anteriormente. Veja o exemplo abaixo:

[
    {
        "question": "INITIALMESSAGE1",            
        "contents": [
            {
                "text": "Bem vindo!",
                "type": "TEXT"
            }            
        ],
        "conversationId": "4e42069c-6149-4dd2-90a5-47c13cfa4b67",
        "date": "2025-09-29T15:26:03",
        "empty": false,
        "msgProcStartedTime": "2025-09-29T15:26:03-03",
        "noAnswerFound": false,
        "agentHandover": false,
        "ui": {
        }
    },
    {            
        "question": "qual a capital da França?",
        "contents": [
            {
                "text": "No momento não sei falar sobre isso. Vamos falar de outra coisa?",
                "type": "TEXT"
            }
        ],
        "conversationId": "4e42069c-6149-4dd2-90a5-47c13cfa4b67",
        "date": "2025-09-29T15:26:08",
        "empty": false,
        "msgProcStartedTime": "2025-09-29T15:26:08-03",
        "noAnswerFound": false,
        "agentHandover": false,
        "ui": {
        }
    }
]

Atenção!

O histórico só fica disponível enquanto a conversa estiver ativa. Se ela expirar, geralmente após o tempo de ociosidade configurado no canal web, ele não irá mais retornar mensagens e indicará o erro 404 (não encontrado).

Buscando o Histórico nas Integrações

Um padrão que pode ser útil é o seu chatbot acionar uma integração que por sua vez irá buscar o histórico nesse endpoint. Para tanto, é importante que a integração conheça o Identificador do Chatbot e o Identificador da Conversa, o que pode ser feito através das variáveis sb_chatbot_id e sb_conversation_id (vide palavras reservadas).