Operaciones Masivas

curl -X POST https://api.whaapy.com/contacts/v1/bulk \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "create",
    "contacts": [
      { "phone_number": "+5215512345678", "name": "Juan", "tags": ["lead"] },
      { "phone_number": "+5215587654321", "name": "María", "tags": ["lead"] },
      { "phone_number": "+5215511223344", "name": "Pedro", "tags": ["lead"] }
    ]
  }'

const response = await fetch('https://api.whaapy.com/contacts/v1/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_TU_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    operation: 'create',
    contacts: [
      { phone_number: '+5215512345678', name: 'Juan', tags: ['lead'] },
      { phone_number: '+5215587654321', name: 'María', tags: ['lead'] },
      { phone_number: '+5215511223344', name: 'Pedro', tags: ['lead'] }
    ]
  })
});

import requests

response = requests.post(
    'https://api.whaapy.com/contacts/v1/bulk',
    headers={
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'operation': 'create',
        'contacts': [
            {'phone_number': '+5215512345678', 'name': 'Juan', 'tags': ['lead']},
            {'phone_number': '+5215587654321', 'name': 'María', 'tags': ['lead']},
            {'phone_number': '+5215511223344', 'name': 'Pedro', 'tags': ['lead']}
        ]
    }
)

{
  "operation": "add_tags",
  "success_count": 3,
  "error_count": 0,
  "results": [
    { "contact_id": "uuid-1", "success": true },
    { "contact_id": "uuid-2", "success": true },
    { "contact_id": "uuid-3", "success": true }
  ]
}

POST

contacts

bulk

curl -X POST https://api.whaapy.com/contacts/v1/bulk \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "create",
    "contacts": [
      { "phone_number": "+5215512345678", "name": "Juan", "tags": ["lead"] },
      { "phone_number": "+5215587654321", "name": "María", "tags": ["lead"] },
      { "phone_number": "+5215511223344", "name": "Pedro", "tags": ["lead"] }
    ]
  }'

const response = await fetch('https://api.whaapy.com/contacts/v1/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_TU_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    operation: 'create',
    contacts: [
      { phone_number: '+5215512345678', name: 'Juan', tags: ['lead'] },
      { phone_number: '+5215587654321', name: 'María', tags: ['lead'] },
      { phone_number: '+5215511223344', name: 'Pedro', tags: ['lead'] }
    ]
  })
});

import requests

response = requests.post(
    'https://api.whaapy.com/contacts/v1/bulk',
    headers={
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'operation': 'create',
        'contacts': [
            {'phone_number': '+5215512345678', 'name': 'Juan', 'tags': ['lead']},
            {'phone_number': '+5215587654321', 'name': 'María', 'tags': ['lead']},
            {'phone_number': '+5215511223344', 'name': 'Pedro', 'tags': ['lead']}
        ]
    }
)

{
  "operation": "add_tags",
  "success_count": 3,
  "error_count": 0,
  "results": [
    { "contact_id": "uuid-1", "success": true },
    { "contact_id": "uuid-2", "success": true },
    { "contact_id": "uuid-3", "success": true }
  ]
}

Realiza operaciones masivas sobre contactos: crear, actualizar, eliminar, gestionar tags y mover en el funnel.

Límites:

Máximo 100 contactos por request
Rate limit: 10 requests/minuto para operaciones bulk

Operaciones Disponibles

Operación	Descripción
`create`	Crear múltiples contactos
`update`	Actualizar múltiples contactos
`delete`	Eliminar múltiples contactos (soft delete)
`add_tags`	Agregar tags a múltiples contactos
`remove_tags`	Remover tags de múltiples contactos
`set_funnel_stage`	Mover contactos a una etapa del funnel

Body Parameters

string

required

Tipo de operación: create, update, delete, add_tags, remove_tags, set_funnel_stage

array

Para create y update: Array de objetos de contacto

string[]

Para delete, add_tags, remove_tags, set_funnel_stage: Array de UUIDs

string[]

Para add_tags y remove_tags: Tags a agregar/remover

string

Para set_funnel_stage: UUID de la etapa destino

Ejemplos por Operación

Crear Múltiples Contactos

curl -X POST https://api.whaapy.com/contacts/v1/bulk \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "create",
    "contacts": [
      { "phone_number": "+5215512345678", "name": "Juan", "tags": ["lead"] },
      { "phone_number": "+5215587654321", "name": "María", "tags": ["lead"] },
      { "phone_number": "+5215511223344", "name": "Pedro", "tags": ["lead"] }
    ]
  }'

const response = await fetch('https://api.whaapy.com/contacts/v1/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_TU_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    operation: 'create',
    contacts: [
      { phone_number: '+5215512345678', name: 'Juan', tags: ['lead'] },
      { phone_number: '+5215587654321', name: 'María', tags: ['lead'] },
      { phone_number: '+5215511223344', name: 'Pedro', tags: ['lead'] }
    ]
  })
});

import requests

response = requests.post(
    'https://api.whaapy.com/contacts/v1/bulk',
    headers={
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'operation': 'create',
        'contacts': [
            {'phone_number': '+5215512345678', 'name': 'Juan', 'tags': ['lead']},
            {'phone_number': '+5215587654321', 'name': 'María', 'tags': ['lead']},
            {'phone_number': '+5215511223344', 'name': 'Pedro', 'tags': ['lead']}
        ]
    }
)

Agregar Tags Masivamente

{
  "operation": "add_tags",
  "contact_ids": [
    "uuid-1",
    "uuid-2",
    "uuid-3"
  ],
  "tags": ["campaña-enero", "newsletter"]
}

Remover Tags

{
  "operation": "remove_tags",
  "contact_ids": ["uuid-1", "uuid-2"],
  "tags": ["lead", "sin-atender"]
}

Mover a Etapa del Funnel

{
  "operation": "set_funnel_stage",
  "contact_ids": ["uuid-1", "uuid-2"],
  "funnel_stage_id": "stage-qualified-uuid"
}

Actualizar Múltiples Contactos

{
  "operation": "update",
  "contacts": [
    { 
      "id": "uuid-1", 
      "add_tags": ["verificado"],
      "custom_fields": { "verified_at": "2026-01-28" }
    },
    { 
      "id": "uuid-2", 
      "add_tags": ["verificado"],
      "custom_fields": { "verified_at": "2026-01-28" }
    }
  ]
}

Eliminar Múltiples Contactos

{
  "operation": "delete",
  "contact_ids": ["uuid-1", "uuid-2", "uuid-3"]
}

Respuestas

Operación Exitosa

{
  "operation": "add_tags",
  "success_count": 3,
  "error_count": 0,
  "results": [
    { "contact_id": "uuid-1", "success": true },
    { "contact_id": "uuid-2", "success": true },
    { "contact_id": "uuid-3", "success": true }
  ]
}

Con Errores Parciales

{
  "operation": "create",
  "success_count": 2,
  "error_count": 1,
  "results": [
    { 
      "phone_number": "+5215512345678", 
      "success": true, 
      "contact_id": "new-uuid-1" 
    },
    { 
      "phone_number": "+5215587654321", 
      "success": true, 
      "contact_id": "new-uuid-2" 
    },
    { 
      "phone_number": "+5215511223344", 
      "success": false, 
      "error": "duplicate_contact",
      "existing_contact_id": "existing-uuid"
    }
  ]
}

El código 207 Multi-Status indica que algunas operaciones tuvieron éxito y otras fallaron. Revisa el array results para ver el detalle de cada una.

Errores Posibles en Results

Error	Descripción
`not_found`	Contacto no encontrado
`duplicate_contact`	Ya existe un contacto con ese teléfono
`invalid_phone_number`	Número de teléfono inválido
`create_failed`	Error al crear contacto
`update_failed`	Error al actualizar contacto
`delete_failed`	Error al eliminar contacto
`add_tags_failed`	Error al agregar tags
`remove_tags_failed`	Error al remover tags
`set_funnel_failed`	Error al asignar etapa del funnel

Casos de Uso

Importar contactos de CSV

Después de parsear un archivo CSV, crea los contactos en lote:

const contacts = csvRows.map(row => ({
  phone_number: row.telefono,
  name: row.nombre,
  email: row.email,
  tags: ['importado-csv']
}));

// Dividir en chunks de 100
for (let i = 0; i < contacts.length; i += 100) {
  await api.post('/contacts/v1/bulk', {
    operation: 'create',
    contacts: contacts.slice(i, i + 100)
  });
}

Etiquetar resultados de campaña

Después de enviar una campaña, etiqueta los contactos:

{
  "operation": "add_tags",
  "contact_ids": ["...ids de la campaña..."],
  "tags": ["campaña-enero-2026", "email-enviado"]
}

Limpiar contactos inactivos

Elimina contactos que no han interactuado en 1 año:

{
  "operation": "delete",
  "contact_ids": ["...ids de búsqueda avanzada..."]
}

Próximos Pasos

Búsqueda Avanzada

Encontrar contactos para operaciones masivas

Listar Contactos

Ver contactos actualizados

Fusionar Contactos

Combinar duplicados

Listar Tags

Ver tags disponibles

General

Mensajes

Media

Conversaciones

Contactos

Segmentos

Funnels

Templates

Agente IA

Equipo

Webhooks

Operaciones Disponibles

Body Parameters

Ejemplos por Operación

Crear Múltiples Contactos

Agregar Tags Masivamente

Remover Tags

Mover a Etapa del Funnel

Actualizar Múltiples Contactos

Eliminar Múltiples Contactos

Respuestas

Operación Exitosa

Con Errores Parciales

Errores Posibles en Results

Casos de Uso

Próximos Pasos

Búsqueda Avanzada

Listar Contactos

Fusionar Contactos

Listar Tags

​Operaciones Disponibles

​Body Parameters

​Ejemplos por Operación

​Crear Múltiples Contactos

​Agregar Tags Masivamente

​Remover Tags

​Mover a Etapa del Funnel

​Actualizar Múltiples Contactos

​Eliminar Múltiples Contactos

​Respuestas

​Operación Exitosa

​Con Errores Parciales

​Errores Posibles en Results

​Casos de Uso

​Próximos Pasos

Búsqueda Avanzada

Listar Contactos

Fusionar Contactos

Listar Tags

Operaciones Disponibles

Body Parameters

Ejemplos por Operación

Crear Múltiples Contactos

Agregar Tags Masivamente

Remover Tags

Mover a Etapa del Funnel

Actualizar Múltiples Contactos

Eliminar Múltiples Contactos

Respuestas

Operación Exitosa

Con Errores Parciales

Errores Posibles en Results

Casos de Uso

Próximos Pasos