> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whaapy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar Contactos

> Envía tarjetas de contacto (vCard) por WhatsApp

Comparte información de contacto como tarjetas vCard. El usuario podrá guardar el contacto directamente en su agenda.

<Note>
  Los contactos solo pueden enviarse dentro de la ventana de 24 horas. Fuera de la ventana, usa [templates](/api-reference/messages/send-templates).
</Note>

***

## Ejemplo Básico

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.whaapy.com/messages/v1 \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+5215512345678",
      "type": "contacts",
      "contacts": [
        {
          "name": {
            "formatted_name": "Juan Pérez",
            "first_name": "Juan",
            "last_name": "Pérez"
          },
          "phones": [
            {
              "phone": "+5215598765432",
              "type": "WORK"
            }
          ]
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.whaapy.com/messages/v1', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer wha_TU_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+5215512345678',
      type: 'contacts',
      contacts: [
        {
          name: {
            formatted_name: 'Juan Pérez',
            first_name: 'Juan',
            last_name: 'Pérez'
          },
          phones: [
            {
              phone: '+5215598765432',
              type: 'WORK'
            }
          ]
        }
      ]
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.whaapy.com/messages/v1',
      headers={
          'Authorization': 'Bearer wha_TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'to': '+5215512345678',
          'type': 'contacts',
          'contacts': [
              {
                  'name': {
                      'formatted_name': 'Juan Pérez',
                      'first_name': 'Juan',
                      'last_name': 'Pérez'
                  },
                  'phones': [
                      {
                          'phone': '+5215598765432',
                          'type': 'WORK'
                      }
                  ]
              }
          ]
      }
  )
  ```
</RequestExample>

***

## Contacto Completo

<RequestExample>
  ```json Request theme={null}
  {
    "to": "+5215512345678",
    "type": "contacts",
    "contacts": [
      {
        "name": {
          "formatted_name": "Juan Pérez García",
          "first_name": "Juan",
          "last_name": "Pérez",
          "middle_name": "García",
          "prefix": "Lic.",
          "suffix": "Jr."
        },
        "phones": [
          {
            "phone": "+5215598765432",
            "type": "WORK",
            "wa_id": "5215598765432"
          },
          {
            "phone": "+5215512345678",
            "type": "CELL"
          }
        ],
        "emails": [
          {
            "email": "juan.perez@empresa.com",
            "type": "WORK"
          },
          {
            "email": "juanp@gmail.com",
            "type": "HOME"
          }
        ],
        "addresses": [
          {
            "street": "Av. Reforma 123",
            "city": "Ciudad de México",
            "state": "CDMX",
            "zip": "06600",
            "country": "México",
            "country_code": "MX",
            "type": "WORK"
          }
        ],
        "org": {
          "company": "Whaapy Inc.",
          "department": "Ventas",
          "title": "Director de Ventas"
        },
        "urls": [
          {
            "url": "https://whaapy.com",
            "type": "WORK"
          },
          {
            "url": "https://linkedin.com/in/juanperez",
            "type": "WORK"
          }
        ],
        "birthday": "1990-05-15"
      }
    ]
  }
  ```
</RequestExample>

***

## Múltiples Contactos

Puedes enviar varios contactos en un solo mensaje:

<RequestExample>
  ```json Request theme={null}
  {
    "to": "+5215512345678",
    "type": "contacts",
    "contacts": [
      {
        "name": {
          "formatted_name": "Soporte Técnico",
          "first_name": "Soporte"
        },
        "phones": [
          { "phone": "+5215500001111", "type": "WORK" }
        ]
      },
      {
        "name": {
          "formatted_name": "Ventas",
          "first_name": "Ventas"
        },
        "phones": [
          { "phone": "+5215500002222", "type": "WORK" }
        ]
      },
      {
        "name": {
          "formatted_name": "Facturación",
          "first_name": "Facturación"
        },
        "phones": [
          { "phone": "+5215500003333", "type": "WORK" }
        ]
      }
    ]
  }
  ```
</RequestExample>

***

## Campos

### Objeto Contact

<ParamField body="contacts" type="array" required>
  Array de objetos de contacto. Puedes enviar múltiples contactos.
</ParamField>

### Objeto Name (requerido)

<ParamField body="name.formatted_name" type="string" required>
  Nombre completo formateado. Este es el campo principal que ve el usuario.
</ParamField>

<ParamField body="name.first_name" type="string">
  Nombre de pila.
</ParamField>

<ParamField body="name.last_name" type="string">
  Apellido.
</ParamField>

<ParamField body="name.middle_name" type="string">
  Segundo nombre o apellido materno.
</ParamField>

<ParamField body="name.prefix" type="string">
  Prefijo (Dr., Lic., Ing., etc.).
</ParamField>

<ParamField body="name.suffix" type="string">
  Sufijo (Jr., Sr., III, etc.).
</ParamField>

### Objeto Phone

<ParamField body="phones[].phone" type="string" required>
  Número de teléfono con código de país.
</ParamField>

<ParamField body="phones[].type" type="string">
  Tipo: `CELL`, `MAIN`, `IPHONE`, `HOME`, `WORK`.
</ParamField>

<ParamField body="phones[].wa_id" type="string">
  ID de WhatsApp (solo si el número tiene WhatsApp).
</ParamField>

### Objeto Email

<ParamField body="emails[].email" type="string" required>
  Dirección de correo electrónico.
</ParamField>

<ParamField body="emails[].type" type="string">
  Tipo: `HOME`, `WORK`.
</ParamField>

### Objeto Address

<ParamField body="addresses[].street" type="string">
  Calle y número.
</ParamField>

<ParamField body="addresses[].city" type="string">
  Ciudad.
</ParamField>

<ParamField body="addresses[].state" type="string">
  Estado o provincia.
</ParamField>

<ParamField body="addresses[].zip" type="string">
  Código postal.
</ParamField>

<ParamField body="addresses[].country" type="string">
  País.
</ParamField>

<ParamField body="addresses[].country_code" type="string">
  Código ISO del país (MX, US, ES, etc.).
</ParamField>

<ParamField body="addresses[].type" type="string">
  Tipo: `HOME`, `WORK`.
</ParamField>

### Objeto Organization

<ParamField body="org.company" type="string">
  Nombre de la empresa.
</ParamField>

<ParamField body="org.department" type="string">
  Departamento.
</ParamField>

<ParamField body="org.title" type="string">
  Cargo o título.
</ParamField>

### Objeto URL

<ParamField body="urls[].url" type="string" required>
  URL del sitio web o perfil.
</ParamField>

<ParamField body="urls[].type" type="string">
  Tipo: `HOME`, `WORK`.
</ParamField>

### Otros Campos

<ParamField body="birthday" type="string">
  Fecha de nacimiento en formato `YYYY-MM-DD`.
</ParamField>

***

## Respuesta Exitosa

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "messaging_product": "whatsapp",
    "contacts": [
      { "input": "+5215512345678", "wa_id": "5215512345678" }
    ],
    "messages": [
      { "id": "550e8400-e29b-41d4-a716-446655440000", "wamid": "wamid.HBgLNTIxNTUx..." }
    ],
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "conversationId": "660e8400-e29b-41d4-a716-446655440001",
      "messageType": "contacts",
      "direction": "outbound",
      "status": "sent",
      "createdAt": "2026-01-22T10:30:00Z"
    }
  }
  ```
</ResponseExample>

***

## Casos de Uso

<AccordionGroup>
  <Accordion title="Compartir datos del asesor">
    ```json theme={null}
    {
      "contacts": [{
        "name": { "formatted_name": "María López - Tu Asesora" },
        "phones": [{ "phone": "+5215512345678", "type": "WORK", "wa_id": "5215512345678" }],
        "emails": [{ "email": "maria.lopez@empresa.com", "type": "WORK" }],
        "org": { "company": "Empresa SA", "title": "Asesora de Ventas" }
      }]
    }
    ```
  </Accordion>

  <Accordion title="Directorio de departamentos">
    ```json theme={null}
    {
      "contacts": [
        {
          "name": { "formatted_name": "Soporte Técnico" },
          "phones": [{ "phone": "+5215500001111", "type": "WORK" }],
          "emails": [{ "email": "soporte@empresa.com", "type": "WORK" }]
        },
        {
          "name": { "formatted_name": "Ventas" },
          "phones": [{ "phone": "+5215500002222", "type": "WORK" }],
          "emails": [{ "email": "ventas@empresa.com", "type": "WORK" }]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Tarjeta de negocio">
    ```json theme={null}
    {
      "contacts": [{
        "name": { 
          "formatted_name": "Restaurante La Parrilla",
          "first_name": "La Parrilla"
        },
        "phones": [
          { "phone": "+5215512345678", "type": "WORK" },
          { "phone": "+5215598765432", "type": "CELL" }
        ],
        "addresses": [{
          "street": "Av. Insurgentes 456",
          "city": "CDMX",
          "country": "México",
          "type": "WORK"
        }],
        "urls": [{ "url": "https://laparrilla.mx", "type": "WORK" }]
      }]
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Enviar Reacciones" icon="face-smile" href="/api-reference/messages/send-reactions">
    Reacciona a mensajes con emojis
  </Card>

  <Card title="Reintentar Mensaje" icon="rotate" href="/api-reference/messages/retry">
    Reenviar mensajes fallidos
  </Card>
</CardGroup>