Send a free-form WhatsApp message

Request

Envía un mensaje de WhatsApp que no es una plantilla: texto, o media de tipo imagen, documento, audio o video, con texto opcional como caption. Funciona tanto con la conexión oficial (BSP/Gupshup) como con una línea QR.

El destinatario se identifica con phone_number o customer_id. Si se envían ambos, se usa customer_id; si ese customer_id no existe, se usa phone_number. Si el cliente no existe, se crea.
El cliente debe tener teléfono o user_id; si no, responde 422.
La línea se elige con integration_id, el mismo id que devuelve GET /retailers/api/v1/whatsapp_templates/integrations (que incluye BSP, Gupshup y QR). Con una sola línea no es necesario; con varias es obligatorio un integration_id válido.
Media permitida: imágenes JPG/JPEG/PNG, documentos PDF/DOC/DOCX/XLS/XLSX, audio MP3/OGG/OGA/OPUS/M4A/AAC/WAV y video MP4/3GP/MOV/M4V.
Mercately no valida la ventana de 24 horas: intenta el envío y, si el proveedor lo rechaza, devuelve su mensaje de error tal cual. En QR no existe esa ventana.
POST /retailers/api/v1/whatsapp/send_message (QR, JPG/PNG/PDF) y POST /retailers/api/v1/whatsapp/send_notification_by_id (plantillas) mantienen su contrato.

Security

api-key

Bodyapplication/jsonrequired

phone_numberstring

Número de teléfono del destinatario (formato internacional con +). Se usa cuando no se envía customer_id o cuando ese customer_id no existe. Si no existe, se crea el cliente.

Example:"+593999999999"

customer_idstring

web_id del cliente (obtenido del endpoint de clientes). Tiene prioridad sobre phone_number. Si no existe, se usa phone_number.

Example:"1713huaxq1352"

integration_idstring

Id de la línea de WhatsApp, tal como lo devuelve GET /retailers/api/v1/whatsapp_templates/integrations. Obligatorio si el retailer tiene varias líneas; con una sola línea no hace falta.

Example:"int-1"

messagestring

Texto del mensaje. Si se envía media_url, se usa como caption.

Example:"Hola, ¿cómo estás?"

media_urlstring

URL pública del archivo. Permitidos: imágenes JPG/JPEG/PNG, documentos PDF/DOC/DOCX/XLS/XLSX, audio MP3/OGG/OGA/OPUS/M4A/AAC/WAV y video MP4/3GP/MOV/M4V.

Example:"https://mercately.com/example.png"

first_namestring

Nombre del cliente (opcional)

Example:"John"

last_namestring

Apellido del cliente (opcional)

Example:"Doe"

emailstring

Email del cliente (opcional)

Example:"john@example.com"

addressstring

Dirección del cliente (opcional)

Example:"123 Main St"

citystring

Ciudad del cliente (opcional)

Example:"Quito"

statestring

Estado/Provincia del cliente (opcional)

Example:"Pichincha"

zip_codestring

Código postal del cliente (opcional)

Example:"170101"

notesstring

Notas sobre el cliente (opcional)

Example:"Customer notes"

curl -i -X POST \
  https://app.mercately.com/retailers/api/v1/whatsapp/send_open_message \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "phone_number": "+593999999999",
    "customer_id": "1713huaxq1352",
    "integration_id": "int-1",
    "message": "Hola, ¿cómo estás?",
    "media_url": "https://mercately.com/example.png",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "address": "123 Main St",
    "city": "Quito",
    "state": "Pichincha",
    "zip_code": "170101",
    "notes": "Customer notes"
  }'

Responses

Bodyapplication/json

messagestring

Mensaje de confirmación

Example:"Ok"

infoobject(MessageInfo)

Response

{
  "message": "Ok",
  "info": {
    "channel": "whatsapp",
    "content": { … },
    "direction": "outbound",
    "status": "submitted",
    "destination": "+593999999999",
    "country": "EC",
    "created_time": "2022-09-23T16:34:16.768-04:00",
    "error": null
  }
}