Plataforma para desarrolladores

Construir sobre la
Plataforma de conexión

Dos potentes API: una API de servidor RESTful para la gestión de dispositivos y la orquestación de la comunicación, y un protocolo CBBP de bajo nivel para el control directo de las credenciales.

Referencia de la API RESTProtocolo CBBP
OpenAPI 3.0JSON / RESTBluetooth + WiFiSoporte de webhook
Connection Studio
Explorer
examples
send_command.http
response.json
list_devices.http
webhooks.http
src
docs
send_command.http
response.json
# Send a CBBP command via the server
POST /api/v1/devices/{uuid}/cbbp

{
  "command": "speak",
  "object": {
    "text": "Shift starts in 5 minutes",
    "volume": 85,
    "language": "en-US"
  }
}

# Response
{
  "result": 0,
  "detail": "ok"
}
main
HTTPUTF-8Ln 2, Col 1

API REST

Gestión integral del ciclo de vida del dispositivo (aprovisionamiento, configuración, firmware, comunicaciones y análisis) a través de HTTPS estándar.

Explorar la API REST →

Protocolo CBBP

Protocolo básico Com Badge: un protocolo de comandos JSON para el control directo de dispositivos a través de Bluetooth (aplicación), WiFi (servidor proxy) o despacho local.

Explora CBBP →

Webhooks

Suscríbase a los eventos del dispositivo en tiempo real (comunicaciones, cambios de estado, actualizaciones de ubicación) que se envían como cargas útiles HTTP POST a su punto final.

Explorar Webhooks →

Early Access: The Connection API is currently available by special request to select partners. Contact us to apply for access.

Pro or Plus plan required: Badges must be on the Pro or Plus plan to be controlled via the API.

Empezando

Autenticación

La API de conexión utiliza autenticación mediante token Bearer. Todas las solicitudes deben incluir un token de acceso JWT válido en el encabezado de autorización.

Obtén una ficha

Envía tus credenciales al punto final de autenticación. Recibirás un access_token de corta duración y un refresh_token de mayor duración.

Utilice el token

Incluya el token en cada solicitud:

Authorization: Bearer <access_token>
POST/api/v1/auth/login
Pedido
{
  "email": "admin@yourorg.com",
  "password": "••••••••"
}
Respuesta 200
{
  "access_token": "eyJhbG...",
  "refresh_token": "dGhpcw...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

URL base y control de versiones

Todos los puntos finales de la API están versionados bajo /api/v1/. La URL base depende de su implementación.

Para implementaciones alojadas en la nube, utilice el punto final regional asignado a su organización. Para implementaciones de servidor locales, utilice el nombre de host de su servidor.

AmbienteURL base
Nube (EE. UU.)https://beta.connection.app/api/v1
En las instalacioneshttps://<your-server>/api/v1
Tipo de contenido
Todos los cuerpos de solicitud y respuesta utilizan application/json. Incluya Content-Type: application/json en las solicitudes con cuerpo.

Errores y códigos de estado

La API utiliza códigos de estado HTTP estándar. Las respuestas de error incluyen un código legible por máquina y un mensaje legible por humanos.

EstadoSignificado
200Éxito
201Creado
400Solicitud incorrecta: parámetros no válidos
401No autorizado: token faltante o caducado.
403Prohibido: permisos insuficientes
404Extraviado
500Error Interno del Servidor
Respuesta de error
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
API REST

Descripción general de la API REST

La API REST del servidor de conexión proporciona acceso programático completo a su flota de dispositivos, infraestructura de comunicaciones y análisis. Sigue las convenciones RESTful con cuerpos de solicitud/respuesta en formato JSON.

Autenticación de API
Usuarios
Dispositivos
Canales
Comunicación
Puente de audio
Conversaciones
Contenido
Ubicaciones
Notificaciones push
Almacenamiento
Operaciones a granel
Fecha y hora

Autenticación

Autenticación basada en tokens. El inicio de sesión devuelve un token que debe enviarse como autorización: token.<token> en todas las solicitudes posteriores.

POST/api/v1/loginAutentica a un usuario y recibe un token de autenticación.
POST/api/v1/login-deviceAutenticar un dispositivo mediante UUID y dirección MAC.
POST/api/v1/logoutInvalidar el token de sesión actual

Usuarios

Crea y gestiona cuentas de usuario. El endpoint GET /users/user devuelve el usuario actualmente autenticado.

GET/api/v1/users/userRecuperar el perfil del usuario que ha iniciado sesión actualmente.
POST/api/v1/users/userCrear una nueva cuenta de usuario
PATCH/api/v1/users/user/{uuid}Actualizar el perfil de usuario (por ejemplo, la imagen de perfil).

Dispositivos

Permite listar e inspeccionar dispositivos, gestionar las asociaciones entre usuarios y dispositivos, leer y escribir la configuración y el estado de cada dispositivo, gestionar el firmware y las imágenes de almacenamiento, y recibir registros e informes de fallos.

GET/api/v1/devices/deviceEnumerar todos los dispositivos
GET/api/v1/devices/device/{uuid}Obtenga información detallada del dispositivo, incluyendo el firmware y la configuración.
PUT/api/v1/devices/association/{uuid}Actualizar la asociación entre un usuario y un dispositivo.
DELETE/api/v1/devices/association/{uuid}Eliminar la asociación usuario-dispositivo y la configuración almacenada.
GET/api/v1/devices/device/{device_uuid}/settingsLista de ajustes almacenados para un dispositivo
POST/api/v1/devices/device/{device_uuid}/settingsGuardar ajustes específicos del dispositivo
GET/api/v1/devices/device/{device_uuid}/statusObtén el estado del dispositivo (conectividad, batería, sensores, estado del audio).
POST/api/v1/devices/device/{device_uuid}/statusEstado del dispositivo publicado desde el dispositivo
GET/api/v1/devices/device/{device_uuid}/contextEnumerar los valores de contexto almacenados para un dispositivo.
POST/api/v1/devices/device/{device_uuid}/ingest-contextReciba información de GPS y WiFi del dispositivo.
GET/api/v1/devices/firmwareLista de versiones de firmware compatibles con una versión de hardware/software determinada.
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchObtener una imagen de firmware en fragmentos
GET/api/v1/devices/languageLista de idiomas y voces compatibles con el dispositivo.
GET/api/v1/devices/storage_imageDescarga una imagen de almacenamiento de dispositivo personalizada para una configuración regional.
POST/api/v1/devices/logRecibir un archivo de registro de un dispositivo
POST/api/v1/devices/crashRecibir un volcado de memoria de un dispositivo
PATCH/api/v1/devices/crash/{uuid}Actualizar un registro de fallos

Representante de CBBP

Envía cualquier comando CBBP a un dispositivo a través del servidor. El servidor retransmite el comando mediante la conexión Wi-Fi del dispositivo y devuelve la respuesta del dispositivo. La respuesta de salida también incluye un mensaje CBBP que el dispositivo ejecuta inmediatamente.

POST/api/v1/devices/device/{device_uuid}/cbbpEnviar un comando CBBP a un dispositivo a través del servidor.
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Recuperar el estado y la respuesta de un comando CBBP enviado previamente.

El cuerpo de la solicitud es un sobre de comando CBBP. El objeto CBBPCommand almacenado realiza un seguimiento del estado de entrega: NO ESTABLECIDO → ENVIADO → RECIBIDO o TIEMPO DE ESPERA AGOTADO.

Sondeo GET /cbbb/ para comprobar si el dispositivo recibió y respondió al comando.
Solicitud — mensaje saliente
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Respuesta: estado de CBBPCommand
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Canales

Los canales son los elementos básicos de comunicación. Los tipos incluyen ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService y ChannelRecorder.

GET/api/v1/channels/channelLista de canales, opcionalmente filtrados por tipo de objeto.
POST/api/v1/channels/channelCrea un canal (ChannelGroup, ChannelContact o ChannelExternalNumber)
PATCH/api/v1/channels/channel/{uuid}Actualizar un grupo de canales o un contacto de canal.
DELETE/api/v1/channels/channel/{uuid}Eliminar un canal
DELETE/api/v1/channels/{uuid}Eliminar un grupo de canales
DELETE/api/v1/channels/by-type/{channelType}Eliminar todos los canales de un tipo determinado (actualmente ChannelContact)
GET/api/v1/channels/associationEnumerar las asociaciones de canales para el usuario actual.
POST/api/v1/channels/associationSolicitar asociación con un canal
PATCH/api/v1/channels/association/{uuid}Aceptar, rechazar o actualizar la configuración de la asociación
DELETE/api/v1/channels/association/{uuid}Eliminar una asociación con un canal
GET/api/v1/channels/historyObtenga el historial de acceso a canales paginado para el usuario actual.
POST/api/v1/channels/historyCrear una entrada en el historial del canal
GET/api/v1/channels/searchBuscar canales por cadena de consulta y filtro de tipo opcional

Comunicación

Inicia y gestiona sesiones de comunicación activas: llamadas salientes, videoconferencias, grabaciones y transmisión de contenido. La respuesta de llamada saliente incluye un mensaje CBBPMessage que el dispositivo procesa de inmediato.

POST/api/v1/communicate/outgoing-makeIniciar un canal saliente a un ChannelPeople, ChannelGroup, ChannelContact o ChannelContactNumber
POST/api/v1/communicate/incoming-acceptanceAceptar o rechazar una solicitud de unión a un canal entrante
POST/api/v1/communicate/closeCierre el canal de comunicación activo actual en un dispositivo.
POST/api/v1/communicate/vcp-activateIniciar el Protocolo de Comunicación de Voz (VCP) en el servidor y el dispositivo.
POST/api/v1/communicate/vcp-deactivateDesactive VCP y vuelva a cualquier canal anterior.
POST/api/v1/communicate/recording-activateActive el modo de grabación en el servidor y en el dispositivo.
POST/api/v1/communicate/content-startAbrir un canal de transmisión para contenido de audio
POST/api/v1/communicate/request-vocalizationGenerar audio TTS para el texto dado, traduciéndolo opcionalmente.

Puente de audio

Acceda a las grabaciones de las conversaciones de puente, incluyendo transcripciones completas, listas de participantes y resúmenes generados por IA. Admite múltiples plantillas de resumen (notas de reuniones, notas de clase, información sanitaria, etc.) y generación de audio TTS para los resúmenes.

GET/api/v1/bridge/conversationsEnumerar todas las conversaciones del puente
GET/api/v1/bridge/conversations/{uuid}Obtenga una conversación detallada que incluye transcripción, participantes y resumen.
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryGenerar un resumen de IA para una conversación.
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioGenerar audio para el resumen de una conversación

Conversaciones

Sesiones de conversación con inteligencia artificial mediante ChatGPT, Gemini o el motor nativo. Admite múltiples perfiles (médico, tutor, mecánico, etc.) e historial de mensajes paginado.

GET/api/v1/conversations/conversationLista de sesiones del generador de IA, filtrables por perfil y herramienta.
POST/api/v1/conversations/conversationCrear una nueva sesión de conversación con IA
GET/api/v1/conversations/conversation/{uuid}Recuperar una sesión de conversación con resumen/actualización de ausencia opcional
DELETE/api/v1/conversations/conversation/{uuid}Eliminar una sesión de conversación
GET/api/v1/conversations/conversation/{uuid}/messagesEnumerar los mensajes de una conversación
POST/api/v1/conversations/conversation/{uuid}/messagesAñade un mensaje de usuario y recibe una respuesta de IA.

Contenido

Explora y reproduce contenido de audio en streaming en tus dispositivos. El contenido está organizado en una estructura de categorías; puedes filtrar el contenido más popular por ciudad, región o país.

GET/api/v1/content/categoriesObtén un árbol de categorías de contenido
GET/api/v1/content/contentEnumerar el contenido disponible dentro de una categoría.
GET/api/v1/content/popularEnumera el contenido popular de una ciudad, región o país determinado.

Ubicaciones

Convierte las coordenadas geográficas en un objeto estructurado de ciudad, región y país. Los dispositivos lo utilizan al procesar el contexto.

POST/api/v1/location/determineDeterminar la latitud/longitud a ciudad, región y país.

Notificaciones push

Registra una aplicación móvil para recibir notificaciones push de FCM. Compatible con iOS, Android y web.

POST/api/v1/push-notifications/pushRegistra una aplicación móvil para recibir notificaciones push de FCM (iOS, Android, web).

Almacenamiento

Descarga los archivos almacenados en los objetos del modelo y ejecuta la eliminación del fondo de la imagen (devuelve el resultado codificado en base64).

GET/api/v1/storage/retrieve/{path}Descargar un archivo almacenado por ruta
POST/api/v1/storage/remove-backgroundElimina el fondo de una imagen (devuelve base64).

Operaciones a granel

Ejecuta varias operaciones de API en una sola solicitud HTTP. Pasa single_transaction=true para agrupar todas las operaciones en una transacción atómica; si falla cualquier elemento, se revertirá todo el lote.

POST/api/v1/bulkEjecuta múltiples operaciones de API en una sola solicitud, opcionalmente como una única transacción atómica.

Fecha y hora

Devuelve la fecha y hora actuales del servidor en GMT+0. No requiere autenticación. Los dispositivos lo utilizan para sincronizar su reloj interno.

GET/api/v1/current-datetimeDevuelve la fecha y hora actuales en GMT+0.
Protocolo CBBP

Protocolo básico de insignias Com

CBBP es un protocolo de comandos JSON ligero para la interacción directa con las insignias Connection. Te brinda control total sobre todas las funciones de hardware y software del dispositivo.

Formato del mensaje

Cada interacción CBBP consiste en un mensaje de comando enviado al dispositivo y un mensaje de resultado devuelto por el dispositivo.

El campo de objeto, tanto en la solicitud como en la respuesta, contiene datos específicos del comando y puede omitirse cuando no sea necesario.

La documentación completa del protocolo está disponible para los socios registrados. Comuníquese con su representante comercial de Connection o póngase en contacto con developer@connectionbadge.com Solicitar acceso a la referencia completa de comandos de CBBP, incluidos los esquemas completos de solicitud/respuesta, los códigos de error y las guías de integración.
Mensaje de comando
{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}
Mensaje de resultado
{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

Transporte

Los mensajes CBBP se pueden entregar a una insignia a través de tres protocolos de transporte diferentes, dependiendo de la arquitectura de integración.

Bluetooth (Aplicación)

Envía comandos CBBP directamente desde una aplicación móvil a través de BLE. Requiere que el dispositivo esté emparejado y dentro del alcance.

SDK móvil

WiFi o Bluetooth a través del servidor

Acceda a CBBP mediante la API REST: POST /devices//cbbbp. El servidor enruta automáticamente la solicitud al dispositivo a través de Wi-Fi o Bluetooth, según la conexión de la insignia. Es la opción más común para integraciones de backend.

API REST

Despacho interno

Despacho CBBP en el dispositivo o entre procesos. Utilizado por el firmware de la insignia para enrutar comandos entre subsistemas internos.

Solo firmware

Comandos de energía

Controla el estado de energía del dispositivo: suspensión, activación, reinicio y restablecimiento de fábrica.

PowerRebootReinicie el dispositivo inmediatamente.
PowerDeepsleepEntrar en modo de suspensión profunda (bajo consumo).
FactoryResetBorra toda la configuración y restablece los valores predeterminados de fábrica.

Comandos WiFi

Configure redes inalámbricas, busque puntos de acceso, compruebe el estado de la conexión y gestione las credenciales guardadas.

WiFiScanEscanee en busca de puntos de acceso WiFi disponibles.
WiFiAPTestPrueba la conectividad con un punto de acceso WiFi específico.
WiFiAPJoinConéctate a un punto de acceso WiFi con las credenciales proporcionadas.

Comandos Bluetooth

Controla la publicidad BLE, el emparejamiento y la comunicación entre dispositivos.

BTScanBTEscanee en busca de dispositivos Bluetooth clásicos.
BTScanBLEEscanee en busca de dispositivos BLE.
DeviceBLEServiceAvailableMarca el servicio BLE como disponible.
DeviceBLEServiceUnavailableMarca el servicio BLE como no disponible.
DeviceBLEActiveConfigure la radio BLE en estado activo.
DeviceBLEIdleConfigure la radio BLE en estado inactivo.
DeviceBLEAdvChannelAddAgregue un canal a la carga útil de publicidad BLE.
DeviceBTScanIniciar un escaneo de dispositivos Bluetooth.
DeviceBTA2DStartIniciar la transmisión de audio Bluetooth A2DP.
DeviceBTA2DEndFinaliza la transmisión de audio Bluetooth A2DP.
DeviceBTNativeAssistStartInicia el asistente de voz Bluetooth nativo.
DeviceBTNativeAssistEndFinaliza el asistente de voz Bluetooth nativo.

Comandos de configuración

Leer y escribir la configuración del dispositivo: nombre para mostrar, zona horaria, idioma e indicadores de funciones.

SettingsListGetRecuperar todas las configuraciones como una lista de pares clave-valor.
SettingsListSetEscribe varios valores de configuración a la vez.
SettingsGetObtén el valor de una configuración específica mediante su clave.
SettingsSetEstablezca el valor de una sola configuración.
SettingsSendEnviar la configuración actual al servidor.
SettingsClearBorrar valores de configuración específicos.
SettingsEraseBorrar todos los ajustes guardados.

Comandos de firmware

Activa las actualizaciones de firmware OTA, comprueba el estado de la actualización y consulta la versión actual del firmware en el dispositivo.

FirmwareCheckComprueba si hay disponible una actualización de firmware.
FirmwareUpdateIniciar una actualización de firmware OTA.
FirmwareValidateValidar la integridad de la imagen de firmware descargada.

Comandos del dispositivo

Ciclo de vida del dispositivo, autenticación, configuración, registro, estado y control de hardware.

NoOpSin operación / mantenimiento activo.
TestPrueba de conectividad básica.
DeviceDateTimeObtenga o configure la fecha y la hora del dispositivo.
DeviceAuthenticateAutentica el dispositivo con el servidor.
DeviceConfigureAplique una carga útil de configuración al dispositivo.
DevicePostConnectionTasksEjecutar las tareas de inicialización posteriores a la conexión.
DeviceStorageLoadCargar datos desde el almacenamiento del dispositivo.
DeviceLoadCustomAudioCarga archivos de audio personalizados en el dispositivo.
DeviceCoredumpSendSube un archivo de volcado de memoria del fallo al servidor.
DeviceAttachConecte el dispositivo a una sesión de servidor.
DeviceDetachDesconecta el dispositivo de la sesión del servidor.
DeviceLogSendSube los registros del dispositivo al servidor.
DeviceConnectionTestPrueba la conectividad del servidor.
DeviceStatusSendEnviar el estado del dispositivo al servidor.
DeviceStatusGetObtén el estado actual del dispositivo.
DeviceInteractionActivar un evento de interacción con el dispositivo.
DeviceSetAPIHostConfigure el host del servidor API.
DeviceTestMicsRealiza una autocomprobación del micrófono.
HardwareI2CCommandEnvía un comando I2C sin procesar a un periférico de hardware.

Comandos de comunicación

Iniciar llamadas, enviar mensajes, gestionar sesiones de comunicación activas y controlar la grabación.

CommunicateChannelJoinÚnete a un canal de comunicación.
CommunicateChannelLeaveDeje un canal de comunicación.
CommunicateChannelChangeCambia a otro canal.
CommunicateChannelCloseCerrar un canal de comunicación.
CommunicateReceiveIncomingNotificar al dispositivo de una comunicación entrante.
CommunicateRequestOutgoingSolicitar una comunicación saliente.
CommunicateVCPActivateActive la sesión del Protocolo de Comunicación de Voz.
CommunicateVCPDeactivateDesactive la sesión de VCP.
CommunicateRecordingActivateComience a grabar la comunicación activa.
CommunicateIncomingAcceptAcepte una llamada entrante.
CommunicateIncomingRejectRechazar una llamada entrante.
CommunicateHFPCallStartIniciar una llamada telefónica Bluetooth HFP.
CommunicateHFPCallEndFinalizar una llamada telefónica Bluetooth HFP.
CommunicateContentStartComience a transmitir contenido de audio al dispositivo.
CommunicateContentStopDeja de transmitir contenido de audio.
SocketReceiveStatusReciba una actualización de estado de WebSocket.

Comandos de audio

Controla el volumen de los altavoces, la ganancia del micrófono, los perfiles de audio y la reproducción de texto a voz.

AudioPlayStorageReproduce un archivo de audio desde el almacenamiento del dispositivo.
AudioPlayContentReproducir contenido de audio en streaming.
AudioSetVolumeAjusta el volumen de salida del altavoz.

Comandos LED

Configura el color, el brillo y los patrones de animación del LED indicador luminoso.

DeviceIlluminationSetConfigura el color y el patrón de iluminación del LED.

Comandos internos

Comandos de despacho internos utilizados para la entrega de contexto, el historial del canal, la vocalización y la decodificación de audio.

InternalSendContextEnviar datos de contexto al gestor de contexto interno.
InternalSendChannelHistoryEnviar el historial del canal al gestor interno.
InternalRequestVocalizationSolicitar la conversión de texto a voz internamente.
InternalHandleVocalizationRTPGestionar una transmisión RTP de vocalización entrante.
InternalDecodeAudioDecodificar una transmisión de audio entrante.

Comandos móviles

Comandos para coordinar la insignia con una aplicación móvil vinculada: notificaciones push, sincronización del estado de la aplicación y enlaces profundos.

MobileServiceStatusInformar sobre el estado del servicio móvil al dispositivo. (Móvil → Dispositivo)
MobileSocketOpenIndica a la aplicación móvil que abra una conexión WebSocket. (Dispositivo → Móvil)
MobileSocketCloseIndica a la aplicación móvil que cierre una conexión WebSocket. (Dispositivo → Móvil)
MobileSocketStatusInformar sobre el estado de WebSocket a la aplicación móvil. (Dispositivo → Móvil)
MobileReceiveStatusInformar del estado de recepción a la aplicación móvil. (Dispositivo → Móvil)
MobileSocketUpdateEnvía una actualización de datos mediante WebSocket a la aplicación móvil. (Dispositivo → Móvil)
MobilePTTStartNotifica a la aplicación móvil que la transmisión PTT ha comenzado. (Dispositivo → Móvil)
MobilePTTStopNotifica a la aplicación móvil que la transmisión PTT ha finalizado. (Dispositivo → Móvil)
MobileContextSetConfigurar datos de contexto en la aplicación móvil. (Dispositivo → Móvil)
MobileEchoComando Echo para probar la conectividad móvil. (Dispositivo → Móvil)

¿Listo para construir?

Únete a la comunidad de desarrolladores de Connection y obtén acceso a dispositivos de prueba, SDK y soporte especializado.

Contáctanos