Pesquisas de Satisfação (NPS)

A plataforma Videochamada.com.br oferece um sistema de pesquisas de satisfação que permite coletar feedback dos participantes das chamadas. O sistema suporta diferentes tipos de perguntas, incluindo NPS (Net Promoter Score).

A pesquisa é configurada no painel, em Projeto → Pesquisa de Satisfação, com até 10 perguntas. Os participantes respondem durante a própria chamada, e as respostas ficam disponíveis pelos endpoints abaixo.

Tipos de Perguntas Suportados

Tipo	Descrição	Escala
`stars`	Avaliação por estrelas	1-5 estrelas
`nps`	Net Promoter Score	0-10
`emojis`	Avaliação por emojis	5 opções (😡 😕 😐 🙂 😍)

Endpoints Disponíveis

Listar Respostas de Pesquisas

Retorna todas as respostas de pesquisas do projeto.

Endpoint: GET /api/surveys/responses

Autenticação: API Key (Bearer Token)

Parâmetros de Consulta:

Parâmetro	Tipo	Descrição
`startDate`	string	Data inicial (ISO 8601). Ex: `2025-01-01`
`endDate`	string	Data final (ISO 8601). Ex: `2025-01-31`
`callId`	string	Filtrar por chamada específica (opcional)

Exemplos de Implementação

curl -X GET "https://api.videochamada.com.br/api/surveys/responses?startDate=2025-01-01&endDate=2025-01-31" \
  -H "Authorization: Bearer {API_TOKEN}"

import requests

response = requests.get(
    "https://api.videochamada.com.br/api/surveys/responses",
    headers={"Authorization": "Bearer {API_TOKEN}"},
    params={
        "startDate": "2025-01-01",
        "endDate": "2025-01-31"
    }
)

const response = await fetch(
  'https://api.videochamada.com.br/api/surveys/responses?startDate=2025-01-01&endDate=2025-01-31',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer {API_TOKEN}'
    }
  }
);

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer {API_TOKEN}");
var response = await client.GetAsync(
    "https://api.videochamada.com.br/api/surveys/responses?startDate=2025-01-01&endDate=2025-01-31"
);

Exemplo de Resposta

A resposta é um array simples. Cada item representa as respostas de um participante (uma sessão) em uma chamada:

[
  {
    "id": "3f8a1b2c-4d5e-6f70-8a9b-0c1d2e3f4a5b",
    "surveyId": "7c6b5a4d-3e2f-1a0b-9c8d-7e6f5a4b3c2d",
    "callId": "5f0e2b7c-3a1d-4c8e-9b6f-2d4a8c1e7f30",
    "sessionId": "session_abc123",
    "answers": [
      {
        "questionId": "9e8d7c6b-5a4f-3e2d-1c0b-9a8f7e6d5c4b",
        "value": 9
      },
      {
        "questionId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "value": 5
      }
    ],
    "created": "2025-01-15T14:30:00Z",
    "call": {
      "id": "5f0e2b7c-3a1d-4c8e-9b6f-2d4a8c1e7f30",
      "status": "ended",
      "created": "2025-01-15T14:00:00Z",
      "started": "2025-01-15T14:02:00Z",
      "ended": "2025-01-15T14:28:00Z"
    }
  }
]

As respostas trazem apenas o questionId

Cada resposta referencia a pergunta pelo questionId e traz o value numérico. O texto e o tipo de cada pergunta não vêm neste endpoint — obtenha-os pelo endpoint de analytics, que retorna text e type por pergunta. O campo call traz os dados da chamada associada.

Se o projeto ainda não tem pesquisa configurada, o endpoint retorna um array vazio ([]).

Obter Analytics de Pesquisas

Retorna estatísticas agregadas das respostas de pesquisa.

Endpoint: GET /api/surveys/analytics

Autenticação: API Key (Bearer Token)

Parâmetros de Consulta:

Parâmetro	Tipo	Descrição
`startDate`	string	Data inicial (ISO 8601)
`endDate`	string	Data final (ISO 8601)

Exemplos de Implementação

curl -X GET "https://api.videochamada.com.br/api/surveys/analytics?startDate=2025-01-01&endDate=2025-01-31" \
  -H "Authorization: Bearer {API_TOKEN}"

import requests

response = requests.get(
    "https://api.videochamada.com.br/api/surveys/analytics",
    headers={"Authorization": "Bearer {API_TOKEN}"},
    params={
        "startDate": "2025-01-01",
        "endDate": "2025-01-31"
    }
)

const response = await fetch(
  'https://api.videochamada.com.br/api/surveys/analytics?startDate=2025-01-01&endDate=2025-01-31',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer {API_TOKEN}'
    }
  }
);

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer {API_TOKEN}");
var response = await client.GetAsync(
    "https://api.videochamada.com.br/api/surveys/analytics?startDate=2025-01-01&endDate=2025-01-31"
);

Exemplo de Resposta

{
  "questions": [
    {
      "questionId": "9e8d7c6b-5a4f-3e2d-1c0b-9a8f7e6d5c4b",
      "text": "Como você avalia o atendimento?",
      "type": "nps",
      "total": 150,
      "average": 8.5,
      "distribution": {
        "0": 2,
        "1": 1,
        "3": 3,
        "4": 2,
        "5": 5,
        "6": 10,
        "7": 15,
        "8": 30,
        "9": 45,
        "10": 37
      }
    },
    {
      "questionId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "text": "Qualidade do vídeo",
      "type": "stars",
      "total": 150,
      "average": 4.2,
      "distribution": {
        "1": 5,
        "2": 10,
        "3": 20,
        "4": 45,
        "5": 70
      }
    }
  ]
}

Note

A distribution inclui apenas os valores que receberam pelo menos uma resposta — valores sem respostas não aparecem como chave. Se o projeto ainda não tem pesquisa configurada, o endpoint retorna {"questions": []}.

Explicação dos Campos de Analytics

Campo	Descrição
`questionId`	Identificador único da pergunta
`text`	Texto da pergunta
`type`	Tipo da pergunta (`nps`, `stars`, `emojis`)
`total`	Total de respostas recebidas
`average`	Média das respostas
`distribution`	Distribuição de respostas por valor

Cálculo do NPS

O Net Promoter Score (NPS) é calculado da seguinte forma:

Promotores (9-10): Clientes satisfeitos e leais
Neutros (7-8): Clientes satisfeitos mas não entusiasmados
Detratores (0-6): Clientes insatisfeitos

Fórmula: NPS = % Promotores - % Detratores

O NPS varia de -100 a +100.

Boas Práticas

Filtros de Data: Use sempre os parâmetros startDate e endDate para evitar retornar grandes volumes de dados
Análise por Chamada: Use o parâmetro callId para analisar feedback de chamadas específicas
Monitoramento Regular: Configure integrações via webhook ou consultas periódicas para acompanhar a satisfação dos clientes

Limitações Atuais

Exportação: Atualmente não há endpoint de exportação em CSV/Excel. Use os endpoints de listagem para obter os dados em JSON
Configuração de Pesquisas: A criação e edição de pesquisas é feita pelo painel administrativo, em Projeto → Pesquisa de Satisfação (não via API pública), com no máximo 10 perguntas por pesquisa