Consultar el estado de los canales
Tres lecturas del lado del servidor listan los canales ocupados, inspeccionan un canal y listan los miembros de un canal de presencia. Autentica cada solicitud con tu clave Bird API y la clave y el secreto de la app de Realtime.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY,
realtime: {
key: process.env.BIRD_REALTIME_KEY,
secret: process.env.BIRD_REALTIME_SECRET,
},
});import os
from bird import Bird
client = Bird(
api_key=os.environ["BIRD_API_KEY"],
realtime_key=os.environ["BIRD_REALTIME_KEY"],
realtime_secret=os.environ["BIRD_REALTIME_SECRET"],
)client, err := bird.NewClient(
option.WithAPIKey(os.Getenv("BIRD_API_KEY")),
option.WithRealtimeCredentials(os.Getenv("BIRD_REALTIME_KEY"), os.Getenv("BIRD_REALTIME_SECRET")),
)
if err != nil {
log.Fatal(err)
}use MessageBird\Bird;
use MessageBird\RealtimeOptions;
$bird = new Bird(
getenv('BIRD_API_KEY') ?: '',
realtime: new RealtimeOptions(
key: getenv('BIRD_REALTIME_KEY') ?: '',
secret: getenv('BIRD_REALTIME_SECRET') ?: '',
),
);Qué canales están ocupados
const { data } = await bird.realtime.channels.list(appId, { prefix: "presence-" });
for (const channel of data) {
console.log(channel.name);
}channels = client.realtime.channels.list(app_id, prefix="presence-")
for channel in channels.data:
print(channel.name)channels, err := client.Realtime.Channels.List(context.Background(), appID, bird.RealtimeChannelListParams{
Prefix: "presence-",
})
if err != nil {
log.Fatal(err)
}
for _, ch := range channels.Data {
fmt.Println(ch.Name)
}$channels = $bird->realtime->channels->list($appId, ['prefix' => 'presence-']);
foreach ($channels->getData() ?? [] as $channel) {
echo $channel->getName(), "\n";
}curl "https://us1.platform.bird.com/v1/realtime/apps/$APP_ID/channels?prefix=presence-" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
-H "X-Realtime-Secret: $BIRD_REALTIME_SECRET"Un canal aparece en la lista mientras al menos una conexión esté suscrita. Los canales no se crean ni se registran por separado, así que los canales vacíos no aparecen. Usa prefix para restringir el resultado a una familia como presence- o orders-.
La respuesta no está paginada y devuelve todos los canales ocupados en una sola instantánea en vivo. Consulta Listar canales de Realtime.
Inspeccionar un canal
const channel = await bird.realtime.channels.get(appId, "presence-lobby", {
include: ["member_count"],
});
if (!channel.occupied) return; // nobody is listening; skip the workchannel = client.realtime.channels.get(app_id, "presence-lobby", include=["member_count"])
if not channel.occupied:
return # nobody is listening; skip the workchannel, err := client.Realtime.Channels.Get(context.Background(), appID, "presence-lobby", bird.RealtimeChannelGetParams{
Include: []bird.RealtimeChannelInclude{bird.RealtimeIncludeMemberCount},
})
if err != nil {
log.Fatal(err)
}
if !channel.Occupied {
return // nobody is listening; skip the work
}$channel = $bird->realtime->channels->get($appId, 'presence-lobby', ['include' => ['member_count']]);
if (!$channel->getOccupied()) {
return; // nobody is listening; skip the work
}curl "https://us1.platform.bird.com/v1/realtime/apps/$APP_ID/channels/presence-lobby?include=member_count" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
-H "X-Realtime-Secret: $BIRD_REALTIME_SECRET"Un nombre desconocido o sin uso devuelve 200 OK con occupied: false. Usa este resultado para omitir trabajo cuando ninguna conexión puede recibirlo. Consulta Obtener un canal de Realtime.
Contadores, mediante include
include es repetible y acepta exactamente dos valores:
- member_count es la cantidad de miembros distintos y solo funciona en canales de presencia.
- connection_count es la cantidad de conexiones suscritas al canal y requiere que la app tenga habilitado el conteo de conexiones.
Cualquier otro valor devuelve 400 Bad Request. API también devuelve 400 Bad Request para member_count en un canal que no es de presencia, una solicitud de lista sin prefijo de presencia, o connection_count cuando el conteo de conexiones está deshabilitado.
Solicitar atributos cuenta como un mensaje extra en el consumo. Omítelos cuando occupied responde tu pregunta.
Un miembro puede tener varias conexiones. Una sala con tres personas que tienen dos pestañas abiertas cada una reporta un member_count de 3 y un connection_count de 6. Canales de presencia explica la distinción.
Quién está presente
const { members } = await bird.realtime.channels.members(appId, "presence-lobby");
for (const member of members) {
console.log(member.member_id);
}presence = client.realtime.channels.members(app_id, "presence-lobby")
for member in presence.members:
print(member.member_id)members, err := client.Realtime.Channels.Members(context.Background(), appID, "presence-lobby")
if err != nil {
log.Fatal(err)
}
for _, m := range members.Members {
fmt.Println(m.MemberId)
}$presence = $bird->realtime->channels->members($appId, 'presence-lobby');
foreach ($presence->getMembers() ?? [] as $member) {
echo $member->getMemberId(), "\n";
}curl "https://us1.platform.bird.com/v1/realtime/apps/$APP_ID/channels/presence-lobby/members" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
-H "X-Realtime-Secret: $BIRD_REALTIME_SECRET"La respuesta contiene solo los IDs de los miembros. member_info se entrega a los clientes suscritos y no está disponible a través de esta operación REST. Cruza los IDs con tus propios registros para mostrar nombres o avatares. Consulta Listar miembros del canal.
Leer el estado mientras publicas
Al publicar, usa include para obtener los mismos contadores de cada canal destino en el momento de la publicación. Consulta Leer el estado del canal mientras publicas.
Comportamiento en un instante dado
Cada respuesta es una instantánea en un instante dado y puede quedar obsoleta de inmediato. Úsala para decisiones puntuales en lugar de hacer polling para estado continuo.
Para estado continuo, suscribe un endpoint a los grupos de webhooks de Realtime. realtime.channel_existence reporta canales ocupados y desocupados, realtime.presence reporta cambios de miembros y realtime.connection_count reporta cambios en el conteo de conexiones. Usa las lecturas de estado de canal para inicializar o reconciliar tu vista almacenada.
Próximos pasos
- Publicar eventos cubre la publicación, el envío por lotes y el atajo include.
- Canales de presencia explica miembros, conexiones y member_info.
- Descripción general de Realtime explica apps, claves y dónde aparece el consumo.
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Explorar la funcionalidadRealtimeSeguir la ruta de aprendizajeBuild your first integrationGuía de implementaciónSend your first realtime event
Prueba el ejercicio y obtén un resumen de implementación