API docs by Redocly

CallMarket API (1.1.0)

Download OpenAPI specification:

API de CallMarket: lanza campañas salientes con un asistente de voz que invita, ofrece promociones, toma reservaciones y pasa la llamada a una persona; y configura el comportamiento del asistente.

Flujo

  1. GET /voces y POST /bots: define el asistente (voz, guion con variables, transferencia, reservas).
  2. Con una clave cmk_test_, crea campañas de prueba: las llamadas son simuladas y no salen a clientes reales.
  3. POST /bots/{id}/revision: CallMarket revisa el guion y lo aprueba.
  4. Con cmk_live_, POST /campanas con tus contactos. Recibes el resultado de cada llamada por webhook.
  5. Si el cliente reserva, recibe la confirmación de su reservación por correo y WhatsApp.

Autenticación y errores

Cabecera X-Api-Key (cmk_test_… = pruebas, cmk_live_… = producción), con los alcances que tenga la clave: bots, campanas, no_contactar, consumo, leads, llamadas, reservas, whatsapp. Máximo 120 peticiones por minuto por clave. Errores: {"error": "codigo", "mensaje": "texto"}. Teléfonos de México a 10 dígitos (acepta +52).

Webhooks firmados

Cada evento es un POST JSON con las cabeceras X-CallMarket-Firma: sha256=<HMAC-SHA256 hex del cuerpo crudo con tu secreto>, X-CallMarket-Evento y X-CallMarket-Id. El secreto se te entrega al registrar tu URL (https). Responde 2xx en menos de 10 s. CallMarket fija tu suscripción a tu cuenta, así no recibes eventos de otros clientes.

Alcance

No se ofrecen campañas por WhatsApp; WhatsApp solo se usa para confirmar una reservación hecha en la llamada.

Bots

Voz, guion, transferencia y reservas del asistente

Voces e idiomas disponibles

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Listar tus bots

Authorizations:
ApiKey
query Parameters
pagina
integer >= 1
Default: 1

Responses

Response samples

Content type
application/json
{
  • "datos": [
    ],
  • "pagina": 0,
  • "hay_mas": true
}

Crear un bot (borrador)

Authorizations:
ApiKey
Request Body schema: application/json
required
nombre
required
string
lugar
required
string

Nombre del lugar tal como lo dirá el bot.

idioma
required
string
Default: "es-MX"
Enum: "es-MX" "en-US"
voz
required
string

Identificador de GET /voces.

guion
required
string <= 8000 characters

Instrucciones del bot. Admite variables {nombre}, {lugar} y cualquier clave enviada en datos del contacto (por ejemplo {ocasion}). Las instrucciones base de CallMarket (identificarse, respetar "no llamar", no inventar datos) siempre van por encima.

apertura
string <= 400 characters

Primera frase del bot.

conocimiento
string <= 20000 characters

Promociones, horarios y políticas que el bot puede citar.

object (Transferencia)

Qué hace el bot cuando el cliente quiere hablar con una persona: ofrece comunicarlo y, con un sí claro, marca al teléfono del lugar. Si nadie contesta en 30 segundos, la llamada vuelve con el bot, que se disculpa y toma los datos para que el lugar le llame (resultado transferencia_fallida).

object (ReservasConfig)

Permite que el bot cree la reservación. Las reglas de seguridad (teléfono y correo obligatorios, máximo de personas, confirmación del cliente antes de crear) las aplica CallMarket y no se pueden desactivar.

Responses

Request samples

Content type
application/json
{
  • "nombre": "Promociones La Pizzería",
  • "lugar": "La Pizzería",
  • "idioma": "es-MX",
  • "voz": "kore",
  • "guion": "string",
  • "apertura": "Hola {nombre}, te llamo de {lugar}.",
  • "conocimiento": "string",
  • "transferencia": {
    },
  • "reservas": {
    }
}

Response samples

Content type
application/json
{
  • "nombre": "Promociones La Pizzería",
  • "lugar": "La Pizzería",
  • "idioma": "es-MX",
  • "voz": "kore",
  • "guion": "string",
  • "apertura": "Hola {nombre}, te llamo de {lugar}.",
  • "conocimiento": "string",
  • "transferencia": {
    },
  • "reservas": {
    },
  • "id": "bot_8f3a1c",
  • "version": 3,
  • "estado": "borrador",
  • "motivo_rechazo": "string",
  • "actualizado": "2019-08-24T14:15:22Z"
}

Ver un bot

Authorizations:
ApiKey
path Parameters
bot_id
required
string

Responses

Response samples

Content type
application/json
{
  • "nombre": "Promociones La Pizzería",
  • "lugar": "La Pizzería",
  • "idioma": "es-MX",
  • "voz": "kore",
  • "guion": "string",
  • "apertura": "Hola {nombre}, te llamo de {lugar}.",
  • "conocimiento": "string",
  • "transferencia": {
    },
  • "reservas": {
    },
  • "id": "bot_8f3a1c",
  • "version": 3,
  • "estado": "borrador",
  • "motivo_rechazo": "string",
  • "actualizado": "2019-08-24T14:15:22Z"
}

Cambiar un bot

Sube version y regresa el bot a borrador.

Authorizations:
ApiKey
path Parameters
bot_id
required
string
Request Body schema: application/json
required
non-empty
nombre
string
lugar
string
idioma
string
Enum: "es-MX" "en-US"
voz
string
guion
string <= 8000 characters
apertura
string <= 400 characters
conocimiento
string <= 20000 characters
object (Transferencia)

Qué hace el bot cuando el cliente quiere hablar con una persona: ofrece comunicarlo y, con un sí claro, marca al teléfono del lugar. Si nadie contesta en 30 segundos, la llamada vuelve con el bot, que se disculpa y toma los datos para que el lugar le llame (resultado transferencia_fallida).

object (ReservasConfig)

Permite que el bot cree la reservación. Las reglas de seguridad (teléfono y correo obligatorios, máximo de personas, confirmación del cliente antes de crear) las aplica CallMarket y no se pueden desactivar.

Responses

Request samples

Content type
application/json
{
  • "nombre": "string",
  • "lugar": "string",
  • "idioma": "es-MX",
  • "voz": "string",
  • "guion": "string",
  • "apertura": "string",
  • "conocimiento": "string",
  • "transferencia": {
    },
  • "reservas": {
    }
}

Response samples

Content type
application/json
{
  • "nombre": "Promociones La Pizzería",
  • "lugar": "La Pizzería",
  • "idioma": "es-MX",
  • "voz": "kore",
  • "guion": "string",
  • "apertura": "Hola {nombre}, te llamo de {lugar}.",
  • "conocimiento": "string",
  • "transferencia": {
    },
  • "reservas": {
    },
  • "id": "bot_8f3a1c",
  • "version": 3,
  • "estado": "borrador",
  • "motivo_rechazo": "string",
  • "actualizado": "2019-08-24T14:15:22Z"
}

Pedir revisión para usarlo en producción

Pasa a en_revision. CallMarket aprueba o rechaza y avisa por correo.

Authorizations:
ApiKey
path Parameters
bot_id
required
string

Responses

Response samples

Content type
application/json
{
  • "nombre": "Promociones La Pizzería",
  • "lugar": "La Pizzería",
  • "idioma": "es-MX",
  • "voz": "kore",
  • "guion": "string",
  • "apertura": "Hola {nombre}, te llamo de {lugar}.",
  • "conocimiento": "string",
  • "transferencia": {
    },
  • "reservas": {
    },
  • "id": "bot_8f3a1c",
  • "version": 3,
  • "estado": "borrador",
  • "motivo_rechazo": "string",
  • "actualizado": "2019-08-24T14:15:22Z"
}

Campañas

Crear, controlar y consultar campañas salientes

Listar campañas

Authorizations:
ApiKey
query Parameters
pagina
integer >= 1
Default: 1

Responses

Response samples

Content type
application/json
{
  • "datos": [
    ],
  • "pagina": 0,
  • "hay_mas": true
}

Crear y programar una campaña

Tú decides a qué contactos se llama. Con clave cmk_test_ la campaña es de prueba (llamadas simuladas). Con cmk_live_ exige un bot aprobado, respeta el horario máximo del plan, tu lista de no contactar y los límites de la cuenta. Si un cliente reserva, recibe la confirmación de su reservación (correo y WhatsApp).

Authorizations:
ApiKey
Request Body schema: application/json
required
nombre
required
string
bot_id
required
string
required
object (Ventana)

Fechas y horario permitido para llamar, en la zona horaria indicada.

object (Reintentos)
object

Variables comunes de la campaña (por ejemplo {promocion}).

required
Array of objects (Contacto) <= 5000 items

Responses

Request samples

Content type
application/json
{
  • "nombre": "Cumpleaños octubre",
  • "bot_id": "bot_8f3a1c",
  • "ventana": {
    },
  • "reintentos": {
    },
  • "datos": {
    },
  • "contactos": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "cmp_91d2e0",
  • "nombre": "string",
  • "bot_id": "string",
  • "ambiente": "prueba",
  • "estado": "programada",
  • "ventana": {
    },
  • "contactos_total": 0,
  • "creada": "2019-08-24T14:15:22Z",
  • "rechazados": [
    ]
}

Ver una campaña

Authorizations:
ApiKey
path Parameters
campana_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "cmp_91d2e0",
  • "nombre": "string",
  • "bot_id": "string",
  • "ambiente": "prueba",
  • "estado": "programada",
  • "ventana": {
    },
  • "contactos_total": 0,
  • "creada": "2019-08-24T14:15:22Z",
  • "rechazados": [
    ]
}

Pausar

Las llamadas en curso terminan; no se marcan más.

Authorizations:
ApiKey
path Parameters
campana_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "cmp_91d2e0",
  • "nombre": "string",
  • "bot_id": "string",
  • "ambiente": "prueba",
  • "estado": "programada",
  • "ventana": {
    },
  • "contactos_total": 0,
  • "creada": "2019-08-24T14:15:22Z",
  • "rechazados": [
    ]
}

Reanudar

Authorizations:
ApiKey
path Parameters
campana_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "cmp_91d2e0",
  • "nombre": "string",
  • "bot_id": "string",
  • "ambiente": "prueba",
  • "estado": "programada",
  • "ventana": {
    },
  • "contactos_total": 0,
  • "creada": "2019-08-24T14:15:22Z",
  • "rechazados": [
    ]
}

Cancelar

Definitivo. Los contactos sin llamar se descartan.

Authorizations:
ApiKey
path Parameters
campana_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "cmp_91d2e0",
  • "nombre": "string",
  • "bot_id": "string",
  • "ambiente": "prueba",
  • "estado": "programada",
  • "ventana": {
    },
  • "contactos_total": 0,
  • "creada": "2019-08-24T14:15:22Z",
  • "rechazados": [
    ]
}

Agregar contactos con la campaña corriendo

Authorizations:
ApiKey
path Parameters
campana_id
required
string
Request Body schema: application/json
required
required
Array of objects (Contacto) <= 5000 items

Responses

Request samples

Content type
application/json
{
  • "contactos": [
    ]
}

Response samples

Content type
application/json
{
  • "agregados": 0,
  • "rechazados": [
    ]
}

Llamadas e intentos de la campaña

Authorizations:
ApiKey
path Parameters
campana_id
required
string
query Parameters
pagina
integer >= 1
Default: 1

Responses

Response samples

Content type
application/json
{
  • "datos": [
    ],
  • "pagina": 0,
  • "hay_mas": true
}

Resumen de la campaña

Authorizations:
ApiKey
path Parameters
campana_id
required
string

Responses

Response samples

Content type
application/json
{
  • "campana_id": "string",
  • "estado": "string",
  • "contactos": 0,
  • "intentos": 0,
  • "contestaron": 0,
  • "no_contestaron": 0,
  • "buzon": 0,
  • "interesados": 0,
  • "reservaron": 0,
  • "transferidos": 0,
  • "no_contactar": 0,
  • "minutos": 0,
  • "costo": {
    }
}

Bajas

Lista de no contactar

Ver tu lista de no contactar

Authorizations:
ApiKey
query Parameters
pagina
integer >= 1
Default: 1

Responses

Response samples

Content type
application/json
{
  • "datos": [
    ],
  • "pagina": 0,
  • "hay_mas": true
}

Agregar números a no contactar

Se respeta en todas tus campañas antes de marcar.

Authorizations:
ApiKey
Request Body schema: application/json
required
required
Array of objects (NoContactar) <= 10000 items

Responses

Request samples

Content type
application/json
{
  • "numeros": [
    ]
}

Response samples

Content type
application/json
{
  • "agregados": 0
}

Leads

Alta y estado de prospectos que el call center llama

Dar de alta un lead para llamarlo

Authorizations:
ApiKey
Request Body schema: application/json
required
telefono
string
Default: ""

10 dígitos (México). Obligatorio; se aceptan los alias phone, phone_number, celular, tel

nombre
string
Default: ""
apellido
string
Default: ""
correo
string
Default: ""
ciudad
string
Default: ""
estado
string
Default: ""
direccion
string
Default: ""
cp
string
Default: ""
comentarios
string
Default: ""

Lo que el cliente escribió o pidió

origen
string
Default: ""

De dónde viene: sitio web, landing, CRM…

campana
string
Default: ""

Producto o campaña de interés

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "telefono": "9994591777",
  • "nombre": "Ana",
  • "apellido": "",
  • "correo": "ana@correo.com",
  • "ciudad": "",
  • "estado": "",
  • "direccion": "",
  • "cp": "",
  • "comentarios": "",
  • "origen": "sitio web",
  • "campana": "flexpei"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "lead_id": 0,
  • "telefono": "string",
  • "estado": "nuevo"
}

Estado de un lead por teléfono

Authorizations:
ApiKey
path Parameters
telefono
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "lead_id": 0,
  • "telefono": "string",
  • "nombre": "",
  • "apellido_o_empresa": "",
  • "estado": "string",
  • "estado_vicidial": "",
  • "ultima_llamada": "",
  • "resumen_bot": ""
}

Llamadas

Llamadas atendidas por el asistente de voz fuera de campañas

Listar llamadas

desde y hasta en segundos epoch. Sin filtros: las últimas limite (máx. 500). Las llamadas de campañas se consultan en /campanas/{id}/llamadas.

Authorizations:
ApiKey
query Parameters
desde
integer
hasta
integer
telefono
string
limite
integer
marca
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "total": 0,
  • "llamadas": [
    ]
}

Reservas

Reservaciones hechas por CallMarket en Resbok

Reservaciones de un teléfono

Authorizations:
ApiKey
query Parameters
telefono
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "reservas": [
    ]
}

Una reservación por folio

Se exige folio y teléfono del cliente.

Authorizations:
ApiKey
path Parameters
folio
required
string
query Parameters
telefono
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "reserva": { }
}

WhatsApp

Mensajes uno a uno con plantillas aprobadas

Enviar una plantilla aprobada

Un mensaje a una persona con una plantilla aprobada por Meta. No es para envíos masivos.

Authorizations:
ApiKey
Request Body schema: application/json
required
telefono
required
string
plantilla
required
string

Nombre de una plantilla APROBADA en Meta

idioma
string
Default: "es_MX"
variables
Array of strings

Valores de {{1}}, {{2}}… en orden

marca
string
Default: ""

Solo si la clave no tiene marca fija

Responses

Request samples

Content type
application/json
{
  • "telefono": "9994591777",
  • "plantilla": "confirmacion_reserva",
  • "idioma": "es_MX",
  • "variables": [
    ],
  • "marca": ""
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "wamid": "string",
  • "a": "string",
  • "marca": "string"
}

Cuenta

Tarifas, límites y consumo

Tarifas vigentes de tu cuenta

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "moneda": "MXN",
  • "configurada": true,
  • "llamada_por_minuto": {
    },
  • "llamada_por_intento": {
    },
  • "transferencia": {
    },
  • "sms": {
    },
  • "tramos_volumen": [
    ],
  • "incremento_segundos": 60,
  • "vigente_desde": "2019-08-24T14:15:22Z"
}

Límites vigentes de tu cuenta

Se amplían conforme crece la capacidad; consúltalos antes de lanzar campañas grandes.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "simultaneas": 5,
  • "llamadas_por_hora": 300,
  • "contactos_por_campana": 5000,
  • "horario_maximo": {
    },
  • "sms_disponible": true
}

Consumo y costo por periodo

Authorizations:
ApiKey
query Parameters
desde
string <date>
hasta
string <date>

Responses

Response samples

Content type
application/json
{
  • "desde": "2019-08-24",
  • "hasta": "2019-08-24",
  • "llamadas": 0,
  • "minutos": 0,
  • "transferencias": 0,
  • "sms": 0,
  • "total": {
    },
  • "por_campana": [
    ]
}

Comprueba la clave y la conexión

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "cliente": "string",
  • "alcances": [
    ],
  • "marca": "string",
  • "version": "string"
}

Webhooks

Avisos que CallMarket envía a tu servidor

Resultado de cada llamada Webhook

Authorizations:
ApiKey
Request Body schema: application/json
id
required
string

Identificador único del evento; úsalo para no procesarlo dos veces.

tipo
required
string
Value: "llamada.resultado"
fecha
required
string <date-time>
marca
string

Identifica tu cuenta.

required
object (EventoLlamada)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "tipo": "llamada.resultado",
  • "fecha": "2019-08-24T14:15:22Z",
  • "marca": "string",
  • "datos": {
    }
}

Cambio de estado de una campaña Webhook

Authorizations:
ApiKey
Request Body schema: application/json
id
required
string

Identificador único del evento; úsalo para no procesarlo dos veces.

tipo
required
string
Value: "campana.estado"
fecha
required
string <date-time>
marca
string

Identifica tu cuenta.

required
object (EventoCampana)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "tipo": "campana.estado",
  • "fecha": "2019-08-24T14:15:22Z",
  • "marca": "string",
  • "datos": {
    }
}

Alguien pidió no ser contactado Webhook

Authorizations:
ApiKey
Request Body schema: application/json
id
required
string

Identificador único del evento; úsalo para no procesarlo dos veces.

tipo
required
string
Value: "contacto.baja"
fecha
required
string <date-time>
marca
string

Identifica tu cuenta.

required
object (EventoBaja)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "tipo": "contacto.baja",
  • "fecha": "2019-08-24T14:15:22Z",
  • "marca": "string",
  • "datos": {
    }
}