API de Llamadas

La API de Llamadas de Positus te permite gestionar llamadas de voz a través de WhatsApp de forma programática. Puedes buscar permisos de llamada, iniciar, aceptar, rechazar y finalizar llamadas.

Autenticación y alcance

Todas las rutas requieren autenticación mediante Bearer Token de usuario y se acceden bajo un número específico:

https://api.positus.global/v2/whatsapp/numbers/{number}/calls
Authorization: Bearer <tu-token>
Content-Type: application/json

Parámetro de ruta	Descripción
`{number}`	UUID de un número activo del usuario

El número debe estar activo y tener calling habilitado en el workspace. Si no es así, la API responde con 404 o 403.

Para recibir eventos de llamada (webhooks), el número debe tener un calls_webhook configurado. Sin esto, no recibirás notificaciones de llamadas entrantes.

Buscar permiso de llamada

Devuelve el estado de permiso para iniciar llamadas con un contacto específico.

GET https://api.positus.global/v2/whatsapp/numbers/{number}/calls/call-permissions?user_wa_id={USER_WA_ID}

Parámetro	Tipo	Obligatorio	Descripción
`user_wa_id`	string	Sí	Número WhatsApp (sin formato) del contacto para el cual deseas buscar permiso

Respuesta:

{
  "number": {
    "uuid": "5dbbbf01-2f92-4389-b512-45de86c4a66f",
    "waba_id": "3243505955080424",
    "user_wa_id": "5543999011234",
    "to": "1131361234"
  },
  "calling": {
    "messaging_product": "whatsapp",
    "permission": {
      "status": "temporary",
      "expiration_time": 1748553340
    },
    "actions": [
      {
        "action_name": "send_call_permission_request",
        "can_perform_action": true,
        "limits": [
          {
            "time_period": "PT24H",
            "max_allowed": 1,
            "current_usage": 0
          },
          {
            "time_period": "P7D",
            "max_allowed": 2,
            "current_usage": 0
          }
        ]
      },
      {
        "action_name": "start_call",
        "can_perform_action": true,
        "limits": [
          {
            "time_period": "PT24H",
            "max_allowed": 5,
            "current_usage": 0
          }
        ]
      }
    ]
  }
}

Modelo de permiso

Entiende los campos devueltos por el endpoint de búsqueda de permisos:

Campo	Descripción
`permission.status`	Estado del permiso: `no_permission` (sin permiso), `temporary` (permiso temporal) o `permanent` (permiso permanente)
`permission.expiration_time`	Timestamp Unix de cuándo expira el permiso (si el estado es `temporary`)
`actions[]`	Lista de acciones disponibles para el contacto
`actions[].action_name`	Nombre de la acción (`send_call_permission_request` o `start_call`)
`actions[].can_perform_action`	`true` si puedes realizar la acción en este momento, `false` en caso contrario
`actions[].limits[]`	Límites aplicados a la acción
`limits[].time_period`	Período del límite: `PT24H` (24 horas) o `P7D` (7 días)
`limits[].max_allowed`	Número máximo de veces que se puede ejecutar la acción en el período
`limits[].current_usage`	Número de veces ya ejecutado en el período actual

Iniciar llamada

Inicia una llamada VoIP con un contacto.

POST https://api.positus.global/v2/whatsapp/numbers/{number}/calls/make

Campo	Tipo	Obligatorio	Descripción
`to`	string	Sí	Número WhatsApp (sin formato) del contacto que recibirá la llamada
`connection.webrtc.sdp`	string	Sí	Descripción de sesión SDP (Session Description Protocol) de tu conexión WebRTC
`session.sdp`	string	Sí	Descripción de sesión SDP para la sesión
`session.sdp_type`	string	No	Tipo de SDP (ej.: `answer`)

Cuerpo de la solicitud:

{
  "to": "551122361741",
  "connection": {
    "webrtc": {
      "sdp": "<<SDP INFO>>"
    }
  },
  "session": {
    "sdp_type": "answer",
    "sdp": "<<RFC 4566 SDP>>"
  }
}

Respuesta:

{
  "success": true
}

Aceptar llamada

Acepta una llamada recibida.

POST https://api.positus.global/v2/whatsapp/numbers/{number}/calls/accept

Campo	Tipo	Obligatorio	Descripción
`call_id`	string	Sí	ID único de la llamada (recibido en el webhook `connect`)
`sdp`	string	Sí	Descripción de sesión SDP (Session Description Protocol) de tu respuesta

Cuerpo de la solicitud:

{
  "call_id": "wacid.HBgMNTU0Mzk5MDU2MDQxFQIAEhggN0JFODFBM0IyMEY3QTNGQkFEQzA0NzhGNEIwNEVGQTQcGAw1NTExMzEzNjE3NDEVAgAA",
  "sdp": "<<SDP INFO>>"
}

Respuesta:

{
  "success": true
}

Rechazar llamada

Rechaza una llamada recibida.

POST https://api.positus.global/v2/whatsapp/numbers/{number}/calls/reject

Campo	Tipo	Obligatorio	Descripción
`call_id`	string	Sí	ID único de la llamada (recibido en el webhook `connect`)

Cuerpo de la solicitud:

{
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh"
}

Respuesta:

{
  "success": true
}

Finalizar llamada

Finaliza una llamada en curso.

POST https://api.positus.global/v2/whatsapp/numbers/{number}/calls/hang-up

Campo	Tipo	Obligatorio	Descripción
`call_id`	string	Sí	ID único de la llamada

Cuerpo de la solicitud:

{
  "call_id": "wacid.HBgMNTU0Mzk5MDU2MDQxFQIAEhggN0JFODFBM0IyMEY3QTNGQkFEQzA0NzhGNEIwNEVGQTQcGAw1NTExMzEzNjE3NDEVAgAA"
}

Respuesta:

{
  "success": true
}

​API de Llamadas

​Autenticación y alcance

​Buscar permiso de llamada

​Modelo de permiso

​Iniciar llamada

​Aceptar llamada

​Rechazar llamada

​Finalizar llamada

API de Llamadas

Autenticación y alcance

Buscar permiso de llamada

Modelo de permiso

Iniciar llamada

Aceptar llamada

Rechazar llamada

Finalizar llamada