Consultar respostas de um evento

Depois de enviar um evento de calendário, os convidados respondem no WhatsApp: vai, não vai ou talvez, com ou sem convidados extras. Esta página mostra como ler essas respostas. Cada convidado tem uma resposta por evento, e a última substitui a anterior.

Para ser avisado na hora em que alguém responde, use o evento de webhook message.calendar_responded (veja Eventos de calendário). As respostas dadas antes de esse recurso existir não estão disponíveis.

Consultar respostas

Endpoint: GET /v1/messages/{message_id}/responses para o número principal. Para números extras, use GET /v1/numbers/{ref}/messages/{message_id}/responses, em que {ref} é o alias atual do número ou o id do número (num_…, o number_id da mensagem).

Escopo obrigatório: messages:read

Parâmetros de caminho:

Parâmetro	Tipo	Descrição
`ref`	string	(apenas na rota de número extra) Alias do número ao qual o evento pertence (`main` ou o alias de um número extra) ou o id dele (`num_…`).
`message_id`	string	Identificador público do evento de calendário (`msg_{hex32}`), o mesmo que o envio devolveu.

curl -X GET \
  https://api.turbonotify.com/v1/messages/msg_01993c5a1b24d3e9f01a2b3c4d5e6f70/responses \
  -H "Authorization: Bearer SUA_CHAVE"

const response = await fetch(
  'https://api.turbonotify.com/v1/messages/msg_01993c5a1b24d3e9f01a2b3c4d5e6f70/responses',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer SUA_CHAVE'
    }
  }
);

const result = await response.json();
console.log(result);

import requests

url = "https://api.turbonotify.com/v1/messages/msg_01993c5a1b24d3e9f01a2b3c4d5e6f70/responses"
headers = {
    "Authorization": "Bearer SUA_CHAVE"
}

response = requests.get(url, headers=headers)
result = response.json()
print(result)

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.turbonotify.com/v1/messages/msg_01993c5a1b24d3e9f01a2b3c4d5e6f70/responses", nil)
    req.Header.Set("Authorization", "Bearer SUA_CHAVE")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

<?php
$url = 'https://api.turbonotify.com/v1/messages/msg_01993c5a1b24d3e9f01a2b3c4d5e6f70/responses';

$options = [
    'http' => [
        'header' => [
            'Authorization: Bearer SUA_CHAVE'
        ],
        'method' => 'GET'
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
var_dump($response);
?>

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer SUA_CHAVE");

var response = await client.GetAsync(
    "https://api.turbonotify.com/v1/messages/msg_01993c5a1b24d3e9f01a2b3c4d5e6f70/responses"
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

import java.net.http.*;
import java.net.URI;

public class TurboNotify {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/messages/msg_01993c5a1b24d3e9f01a2b3c4d5e6f70/responses"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .GET()
            .build();

        var response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Exemplos de resposta

Com respostas

As respostas vêm da mais recente para a mais antiga.

Status HTTP: 200

{
  "message_id": "msg_01993c5a1b24d3e9f01a2b3c4d5e6f70",
  "counts": {
    "going": 2,
    "not_going": 1,
    "maybe": 1,
    "extra_guests": 3
  },
  "responses": [
    {
      "from": {
        "number": "5511999990004",
        "name": "Marina Costa"
      },
      "response": "going",
      "at": "2026-11-03T15:30:00Z"
    },
    {
      "from": {
        "number": "5511999990003",
        "name": "Carlos Lima"
      },
      "response": "maybe",
      "extra_guests": 1,
      "at": "2026-11-03T12:10:00Z"
    },
    {
      "from": {
        "number": "5511999990002",
        "contact_id": "ct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
        "name": "Ana Souza"
      },
      "response": "going",
      "extra_guests": 2,
      "at": "2026-11-03T12:00:00Z"
    },
    {
      "from": {
        "number": "5511999990005"
      },
      "response": "not_going",
      "at": "2026-11-03T11:45:00Z"
    }
  ]
}

Sem respostas

Status HTTP: 200

{
  "message_id": "msg_01993c5a1b24d3e9f01a2b3c4d5e6f70",
  "counts": {
    "going": 0,
    "not_going": 0,
    "maybe": 0,
    "extra_guests": 0
  },
  "responses": []
}

Estrutura da resposta

Campo	Tipo	Descrição
`message_id`	string	Identificador público do evento.
`counts`	object	Totais das últimas respostas. Sempre traz as quatro chaves.
`counts.going`	integer	Convidados cuja última resposta é `going`.
`counts.not_going`	integer	Convidados cuja última resposta é `not_going`.
`counts.maybe`	integer	Convidados cuja última resposta é `maybe`.
`counts.extra_guests`	integer	Total de convidados extras levados por quem respondeu `going` ou `maybe`.
`responses`	array	A última resposta de cada convidado, da mais recente para a mais antiga.
`responses[].from`	object	O convidado.
`responses[].from.number`	string	Telefone do convidado (sem `+`).
`responses[].from.name`	string	Nome do convidado no WhatsApp. Omitido quando não disponível.
`responses[].from.contact_id`	string	Identificador público do contato (`ct_{hex32}`). Omitido quando não disponível.
`responses[].response`	string	`going`, `not_going` ou `maybe`.
`responses[].extra_guests`	integer	Convidados extras que a pessoa leva. Aparece só quando é maior que zero.
`responses[].at`	string	Data e hora ISO 8601 em que a resposta foi dada.

Os dados seguem o prazo das reações: as respostas ficam 12 meses junto com a mensagem. O conteúdo do evento (nome, descrição, local) segue o prazo de conteúdo do seu plano. Veja Retenção.

Erros possíveis

Status	Código de erro	Descrição
`400`	`invalid_message_id`	O `message_id` não tem o formato `msg_{hex32}`.
`400`	`message_not_calendar`	A mensagem não é um evento de calendário.
`401`	`not_authenticated`	A chave de API está inválida ou ausente.
`403`	`insufficient_scope`	A chave de API não possui o escopo `messages:read`.
`404`	`not_found`	A mensagem não foi encontrada, pertence a outra organização ou pertence a um número diferente do da URL (na rota atalho sem `{ref}`, o número principal): todos esses casos devolvem a mesma resposta, sem distinção.
`404`	`number_not_found`	(apenas na rota com `{ref}`) O alias ou o id informado na URL não corresponde a nenhum número cadastrado.
`400`	`invalid_number_id`	(apenas na rota com `{ref}`) O valor na URL começa com `num_`, mas não é um id de número válido.
`500`	`internal_error`	Erro interno inesperado no servidor.