• Construya sus propias integraciones con Voys
• Los cuatro componentes
• API: su software solicita algo de nosotros
• Notificaciones de llamada: nosotros le enviamos algo a usted
• Webhook del plan de marcado: le preguntamos algo mientras el teléfono aún suena
• Clic para llamar: marque con un clic
• Las APIs de un vistazo
• ¿Qué puede construir con esto?
• ¿Construirlo usted mismo o usar algo ya hecho?
• Responsabilidad y soporte
• FAQ

Construya sus propias integraciones con Voys

¿Quiere que su CRM muestre quién llama antes de descolgar? ¿O que una llamada perdida aparezca automáticamente en Slack? Puede hacerlo. Voys dispone de cuatro componentes que permiten que su software y nuestro sistema telefónico se comuniquen entre sí: APIs, notificaciones de llamada, el webhook del plan de marcado y Clic para llamar.

Esta página va más allá de lo básico: aquí también encontrará URLs base, endpoints y ejemplos de peticiones.

Conviene saber antes de empezar:

1. Esta página explica qué es posible hacer con nuestras APIs, pero no es una especificación técnica. Los endpoints, campos y ejemplos pueden cambiar. La documentación actualizada siempre está en el portal OpenAPI, así que úselo como referencia cuando empiece a desarrollar (o compártalo con su programador).
2. Tenga en cuenta que lo que construya con estas APIs, y cómo lo haga, es responsabilidad suya. Voys proporciona la plataforma y la documentación, pero no podemos dar soporte a integraciones personalizadas que usted (o alguien que contrate) desarrolle. Puede leer más sobre esto al final de la página.

Los cuatro componentes

API: su software solicita algo de nosotros

Una API es un mostrador donde su software puede recoger o dejar datos: historial de llamadas, contactos, quién está disponible. Su sistema pregunta, nosotros respondemos.

Voys cuenta con trece APIs, divididas en dos generaciones con su propia dirección cada una:

• Las APIs más recientes funcionan en api.eu-production.holodeck.voys.nl (Contactbook, User status, Call transcription storage).
• El resto funcionan en api.voys.nl/api/v2 (Call, Call recording, Users, VoIP accounts, Caller ID numbers, Webphone user, y las APIs de partner para onboarding).

La autenticación funciona igual en todas partes: un encabezado Authorization: Bearer <su-token> o Authorization: Token <su-token>. Por ejemplo, así es como puede obtener su propio historial de llamadas de las últimas cinco semanas:

GET https://api.voys.nl/api/v2/call/personalized/
Authorization: Bearer <your-token>

Esto devuelve, entre otras cosas, direction, answered, start_time, duration_in_seconds, y quién llamó a quién. Encontrará la lista completa de endpoints y campos en el portal OpenAPI.

Notificaciones de llamada: nosotros le enviamos algo a usted

Esto funciona al revés: en el momento en que algo ocurre con una llamada, se lo enviamos automáticamente a la URL que elija. Su software no tiene que preguntar. Lo notificamos nosotros mismos, como una petición POST con un cuerpo JSON.

Hay seis momentos por llamada: created (solo entrantes), ringing, in progress, warm transfer, cold transfer, y ended (con un motivo: completed, busy, no answer, failed, cancelled, o abandoned). ¿Tiene Voys Intelligence activado? Entonces siguen dos más después de que termine la llamada: call_transcription una vez que la transcripción esté lista, y summary una vez que el resumen de IA esté listo.

Cada notificación incluye al menos un call_id, timestamp, status, direction, y detalles sobre quién llama y el destino. También puede usar ese call_id para obtener la grabación o la transcripción de la misma llamada a través de las APIs correspondientes, así que las notificaciones y las APIs trabajan juntas aquí.

Puede configurar esto usted mismo en Freedom: Integration -> Call notifications -> Add. Elija Custom para su propia URL, o Robin para una integración directa.

Webhook del plan de marcado: le preguntamos algo mientras el teléfono aún suena

Se parece mucho a las notificaciones de llamada, pero funciona al revés. Y ocurre lo suficientemente pronto como para todavía poder hacer algo con la llamada: mientras alguien está llamando, enviamos una petición GET a su servidor preguntando adónde debe ir la llamada. Esto solo funciona para llamadas entrantes, y en exactamente un punto del plan de marcado. Es el único momento en que su sistema puede influir realmente en la llamada.

Los dos son fáciles de confundir, así que aquí está la diferencia: el webhook enruta la llamada (GET, solo entrantes, pide una decisión), mientras que las notificaciones solo informan de lo que ocurrió (POST, cualquier dirección, sin influencia en la llamada). Puede usarlos uno junto al otro en la misma llamada sin ningún problema.

Clic para llamar: marque con un clic

Esto permite que su software inicie una llamada desde el propio dispositivo, app o Teléfono web de alguien. Piense en un botón de llamada junto a cada número de teléfono en su CRM.

• Dirección: https://api.voipgrid.nl/api/clicktodial/. Conviene saber: este es un dominio distinto del resto.
• Autenticación: Authorization: Token <dirección-de-correo>:<su-token>. Funciona de forma ligeramente diferente a las otras APIs: la dirección de correo electrónico del Usuario es parte de ella, separada por dos puntos.

POST https://api.voipgrid.nl/api/clicktodial/
Authorization: Token name@company.com:<your-token>
Content-Type: application/json

{ "b_number": "+31612345678" }

Esto devuelve un callid. ¿Quiere comprobar cómo va la llamada? Entonces consulte GET /api/clicktodial/{callid}/. Obtendrá un estado: conectando (dialing_a, dialing_b), conectado (connected), o terminado/fallido (disconnected, failing_a, failing_b). Aún más fácil: deje que las notificaciones de llamada le avisen cuando la llamada suene, se conteste o termine.

Las APIs de un vistazo

Diez de las trece APIs son para su propio software. Las otras tres (partner client, phone number, y onboarding dial plan) son para partners que dan de alta nuevos clientes, así que las hemos dejado fuera aquí.

Encontrará todos los detalles, campos y parámetros de cada API en el portal OpenAPI.

¿Qué puede construir con esto?

Reconocer llamadas automáticamente. En el momento en que alguien llama, su sistema busca el número en la agenda compartida (API Contactbook) y muestra el nombre y los datos del cliente antes de que se responda la llamada. ¿Quiere además redirigir la llamada según quién esté llamando? Combine esto con el webhook del plan de marcado.

Llamada perdida, aviso inmediato. Recibe una notificación ended con motivo no-answer en su URL. Busca el número a través de la API Contactbook y publica el nombre y el número en el canal de su equipo.

Llamar desde su CRM, con estado en directo. Un compañero hace clic en un número y su integración envía un POST a Clic para llamar. En lugar de consultar repetidamente GET /clicktodial/{callid}/, puede dejar que las notificaciones de llamada (ringing, in-progress, ended) actualicen el registro del CRM.

Grabación, transcripción y resumen llegan al registro del cliente automáticamente. ¿Tiene Voys Intelligence activado? Entonces llega una notificación call recording created después de la llamada, con un recording_url listo para usar, seguida de call_transcription y summary una vez estén listos. Después obtiene las versiones finales a través de la API Call Transcription Storage y las añade al registro.

¿Construirlo usted mismo o usar algo ya hecho?

¿Tiene un desarrollador? Puede empezar enseguida en el portal OpenAPI, donde encontrará la documentación técnica actualizada de las trece APIs. Cada persona puede encontrar su propio token de API en Freedom, en ajustes personales (token de API). Ese token es la clave que su software usa para identificarse ante nosotros, así que trátelo como una contraseña: guárdelo para sí mismo y asegúrese de que nunca acaba en código que otros puedan ver.

¿No tiene un desarrollador a mano? No hay problema, no tiene que empezar desde cero. Ya existen integraciones listas para usar con herramientas populares, como Zapier, Slack, HubSpot, Bubble, ROBIN y Microsoft Teams. Antes de pedir a alguien que construya algo, eche un vistazo a esta página de ayuda sobre Integraciones. Es posible que ya exista una solución para su sistema.

Responsabilidad y soporte

Voys proporciona las APIs, las notificaciones de llamada, el webhook y la documentación de todo ello. Usted decide qué construye con ellas, con quién lo construye y cómo. Eso también significa que la responsabilidad es suya.

En la práctica, esto significa:

• Encantados de ayudarle con: si la API está accesible, si su token funciona, si Voys Intelligence está activado, o si un endpoint o código de estado no coincide con la documentación.
• No podemos ayudarle con: errores en su propio código, un flujo de Zapier que configuró usted mismo y ha dejado de funcionar, o una integración que un tercero construyó para usted y ya no mantiene.

¿Atascado y no sabe de qué lado está el problema? No dude en contactarnos. Estaremos encantados de pensar con usted, aunque la construcción y el mantenimiento de su propia integración queda de su parte (o de su desarrollador).

FAQ

¿Necesito saber programar? No. Esta página le ayuda a entender qué es posible y, a grandes rasgos, cómo se construye. La construcción real la hace un desarrollador, o bien usa una integración ya lista.

¿Es seguro mi token de API? Sí, siempre que lo mantenga en secreto. Cualquiera con ese token puede obtener datos o cambiar ajustes en su nombre. ¿Cree que su token puede haberse filtrado? Puede solicitar uno nuevo en Freedom.

¿Por qué no recibo resúmenes de mis llamadas? En casi todos los casos, es porque Voys Intelligence aún no está activado. Merece la pena comprobarlo primero, antes de buscar más.

¿Puedo hacer que una grabación o transcripción se elimine automáticamente? No es posible, pero no hace falta: caducan por sí solas después del período de retención.

¿Qué pasa si mi integración deja de funcionar? Primero compruebe si el problema está de nuestro lado: el estado de la API, si su token sigue siendo válido, o ajustes como Voys Intelligence. ¿El problema está en su propio código o en una integración de terceros? Entonces usted o su desarrollador deberán arreglarlo. Puede leer más en «Responsabilidad y soporte» más arriba.

¿Hay límites de tasa, y qué ocurre con un 429? Algunos endpoints (como Call Recording) devuelven un 429 throttled si los llama con demasiada frecuencia. No hemos publicado los límites exactos, ni si se incluye una cabecera Retry-After. Para mayor seguridad, incluya un reintento con backoff.

¿Puedo comprobar si una grabación, transcripción o resumen ya está listo? De momento no: no hay campo de estado ni filtro «desde X». La buena noticia es que la notificación de llamada le avisa automáticamente una vez que algo está listo, así que no necesita hacer consultas repetidas.