Skip to main content
POST
/
contacts
/
v1
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"
  }'

{
  "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

​
phone_number
string
required
Número de teléfono en formato E.164. Ej: +5215512345678
​
name
string
Nombre completo del contacto
​
email
string
Email del contacto (debe ser válido)
​
avatar_url
string
URL de imagen de perfil
​
tags
string[]
Array de tags para categorizar. Ej: ["cliente", "premium"]
​
custom_fields
object
Campos personalizados como objeto JSON. Ej: { "company": "Acme" }
​
external_ids
object
IDs externos para integración con CRMs. Ej: { "hubspot": "abc123" }
​
notes
string
Notas internas sobre el contacto
​
funnel_stage_id
string
UUID de la etapa del funnel donde colocar el contacto
​
source
string
default:"api"
Origen del contacto: api, import, webhook, manual, etc.
​
company
string
Nombre de la empresa
​
address
string
Dirección
​
city
string
Ciudad
​
state
string
Estado/Provincia
​
postal_code
string
Código postal
​
country
string
default:"MX"
Código de país ISO 3166-1 alpha-2 (2 letras)
​
assigned_agent_id
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"
  }'

​
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