Crear Contacto

curl -X POST https://api.whaapy.com/contacts/v1 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+5215512345678",
    "name": "Juan Pérez"
  }'

const response = await fetch('https://api.whaapy.com/contacts/v1', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_TU_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '+5215512345678',
    name: 'Juan Pérez'
  })
});
const data = await response.json();
console.log(data.contact);

import requests

response = requests.post(
    'https://api.whaapy.com/contacts/v1',
    headers={
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'phone_number': '+5215512345678',
        'name': 'Juan Pérez'
    }
)
print(response.json())

$ch = curl_init('https://api.whaapy.com/contacts/v1');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer wha_TU_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'phone_number' => '+5215512345678',
    'name' => 'Juan Pérez'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
echo $response;

{
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+5215512345678",
    "name": "Juan Pérez",
    "email": "juan@email.com",
    "avatar_url": null,
    "tags": ["cliente", "premium"],
    "custom_fields": { "company": "Acme Inc" },
    "external_ids": { "hubspot": "abc123" },
    "notes": "Contacto referido por María García",
    "funnel_stage": null,
    "source": "api",
    "company": "Acme Inc",
    "address": null,
    "city": "Ciudad de México",
    "state": null,
    "postal_code": null,
    "country": "MX",
    "assigned_agent_id": null,
    "last_contact_at": null,
    "created_at": "2026-01-28T12:00:00Z",
    "updated_at": "2026-01-28T12:00:00Z"
  }
}

POST

contacts

curl -X POST https://api.whaapy.com/contacts/v1 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+5215512345678",
    "name": "Juan Pérez"
  }'

const response = await fetch('https://api.whaapy.com/contacts/v1', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_TU_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '+5215512345678',
    name: 'Juan Pérez'
  })
});
const data = await response.json();
console.log(data.contact);

import requests

response = requests.post(
    'https://api.whaapy.com/contacts/v1',
    headers={
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'phone_number': '+5215512345678',
        'name': 'Juan Pérez'
    }
)
print(response.json())

$ch = curl_init('https://api.whaapy.com/contacts/v1');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer wha_TU_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'phone_number' => '+5215512345678',
    'name' => 'Juan Pérez'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
echo $response;

{
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+5215512345678",
    "name": "Juan Pérez",
    "email": "juan@email.com",
    "avatar_url": null,
    "tags": ["cliente", "premium"],
    "custom_fields": { "company": "Acme Inc" },
    "external_ids": { "hubspot": "abc123" },
    "notes": "Contacto referido por María García",
    "funnel_stage": null,
    "source": "api",
    "company": "Acme Inc",
    "address": null,
    "city": "Ciudad de México",
    "state": null,
    "postal_code": null,
    "country": "MX",
    "assigned_agent_id": null,
    "last_contact_at": null,
    "created_at": "2026-01-28T12:00:00Z",
    "updated_at": "2026-01-28T12:00:00Z"
  }
}

Agrega un nuevo contacto a tu CRM de Whaapy. El número de teléfono es el único campo requerido.

Body Parameters

string

required

Número de teléfono en formato E.164. Ej: +5215512345678

string

Nombre completo del contacto

string

Email del contacto (debe ser válido)

string

URL de imagen de perfil

string[]

Array de tags para categorizar. Ej: ["cliente", "premium"]

object

Campos personalizados como objeto JSON. Ej: { "company": "Acme" }

object

IDs externos para integración con CRMs. Ej: { "hubspot": "abc123" }

string

Notas internas sobre el contacto

string

UUID de la etapa del funnel donde colocar el contacto

string

default:"api"

Origen del contacto: api, import, webhook, manual, etc.

string

Nombre de la empresa

string

Dirección

string

Ciudad

string

Estado/Provincia

string

Código postal

string

default:"MX"

Código de país ISO 3166-1 alpha-2 (2 letras)

string

UUID del agente humano a asignar al contacto. Obtén IDs de agentes con GET /team/v1. Las conversaciones futuras del contacto se asignarán automáticamente a este agente.

Ejemplos

Contacto Básico

curl -X POST https://api.whaapy.com/contacts/v1 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+5215512345678",
    "name": "Juan Pérez"
  }'

const response = await fetch('https://api.whaapy.com/contacts/v1', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_TU_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '+5215512345678',
    name: 'Juan Pérez'
  })
});
const data = await response.json();
console.log(data.contact);

import requests

response = requests.post(
    'https://api.whaapy.com/contacts/v1',
    headers={
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'phone_number': '+5215512345678',
        'name': 'Juan Pérez'
    }
)
print(response.json())

$ch = curl_init('https://api.whaapy.com/contacts/v1');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer wha_TU_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'phone_number' => '+5215512345678',
    'name' => 'Juan Pérez'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
echo $response;

Contacto Completo

{
  "phone_number": "+5215512345678",
  "name": "Juan Pérez",
  "email": "juan@email.com",
  "tags": ["cliente", "premium"],
  "custom_fields": { 
    "company": "Acme Inc",
    "role": "CEO",
    "contract_value": 50000
  },
  "external_ids": { 
    "hubspot": "abc123" 
  },
  "notes": "Contacto referido por María García",
  "source": "api",
  "company": "Acme Inc",
  "city": "Ciudad de México",
  "country": "MX"
}

Respuesta Exitosa

{
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+5215512345678",
    "name": "Juan Pérez",
    "email": "juan@email.com",
    "avatar_url": null,
    "tags": ["cliente", "premium"],
    "custom_fields": { "company": "Acme Inc" },
    "external_ids": { "hubspot": "abc123" },
    "notes": "Contacto referido por María García",
    "funnel_stage": null,
    "source": "api",
    "company": "Acme Inc",
    "address": null,
    "city": "Ciudad de México",
    "state": null,
    "postal_code": null,
    "country": "MX",
    "assigned_agent_id": null,
    "last_contact_at": null,
    "created_at": "2026-01-28T12:00:00Z",
    "updated_at": "2026-01-28T12:00:00Z"
  }
}

Errores

Contacto Duplicado

{
  "error": "duplicate_contact",
  "message": "Ya existe un contacto con este número de teléfono",
  "existing_contact_id": "550e8400-e29b-41d4-a716-446655440000"
}

Si recibes este error, puedes usar PATCH /contacts/v1/:id para actualizar el contacto existente.

Datos Inválidos

{
  "error": "validation_error",
  "message": "Datos inválidos",
  "details": {
    "phone_number": ["Formato inválido. Usar E.164: +5215512345678"],
    "email": ["Email inválido"]
  }
}

Webhooks

Cuando creas un contacto, se dispara el webhook contact.created:

{
  "event": "contact.created",
  "data": {
    "contact_id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+5215512345678",
    "name": "Juan Pérez",
    "email": "juan@email.com",
    "tags": ["cliente", "premium"],
    "source": "api",
    "created_at": "2026-01-28T12:00:00Z"
  }
}

Próximos Pasos

Operaciones Masivas

Crear múltiples contactos a la vez

Actualizar Contacto

Modificar contacto existente

Enviar Mensaje

Enviar mensaje al nuevo contacto

Webhooks

Ver todos los eventos disponibles

General

Mensajes

Media

Conversaciones

Contactos

Segmentos

Funnels

Templates

Agente IA

Equipo

Webhooks

Body Parameters

Ejemplos

Contacto Básico

Contacto Completo

Respuesta Exitosa

Errores

Contacto Duplicado

Datos Inválidos

Webhooks

Próximos Pasos

Operaciones Masivas

Actualizar Contacto

Enviar Mensaje

Webhooks

​Body Parameters

​Ejemplos

​Contacto Básico

​Contacto Completo

​Respuesta Exitosa

​Errores

​Contacto Duplicado

​Datos Inválidos

​Webhooks

​Próximos Pasos

Operaciones Masivas

Actualizar Contacto

Enviar Mensaje

Webhooks

Body Parameters

Ejemplos

Contacto Básico

Contacto Completo

Respuesta Exitosa

Errores

Contacto Duplicado

Datos Inválidos

Webhooks

Próximos Pasos