# Contactos

> CRUD completo de contactos: crear, buscar, actualizar y eliminar

Fuente: https://developers.plazbot.com/sdk/contact/

### Introducción

El módulo de **Contact** te permite gestionar tu base de contactos de forma programatica. Puedes crear, buscar por teléfono o email, actualizar y eliminar contactos.

### Inicialización

```ts Plazbot (recomendado)
import { Plazbot } from 'plazbot';

const plazbot = new Plazbot({
workspaceId: "YOUR_WORKSPACE_ID",
apiKey: "YOUR_API_KEY",
zone: "LA"
});

// Usar: plazbot.contact.getContacts()
```

```ts Contact individual
import { Contact } from 'plazbot';

const contact = new Contact({
workspaceId: "YOUR_WORKSPACE_ID",
apiKey: "YOUR_API_KEY",
zone: "LA"
});
```

---

### Crear Contacto

```ts
const contact = await plazbot.contact.createContact({
name: "Juan Perez",
cellphone: "51912345678",
email: "juan@ejemplo.com",
tags: ["lead", "web"]
});

console.log("Contacto creado:", contact.id);
```

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `name` | `string` | No | Nombre del contacto |
| `cellphone` | `string` | No | Número de teléfono con código de país |
| `email` | `string` | No | Correo electrónico |
| `tags` | `string[]` | No | Etiquetas de clasificacion |
| `stage` | `string` | No | Etapa del contacto en el pipeline |

---

### Listar Contactos

```ts
const contacts = await plazbot.contact.getContacts();
console.log(`Total: ${contacts.length} contactos`);
```

Devuelve la primera página de contactos (hasta 20), ordenados por última actividad. Para recorrer todos los contactos usa la paginación por cursor.

---

### Paginación: recorrer todos los contactos

`getContactsPage` devuelve páginas de hasta 100 contactos con un cursor. Repite la llamada pasando `nextCursor` hasta recibir `null`:

```ts
let cursor: string | null = null;
let total = 0;

do {
const page = await plazbot.contact.getContactsPage({ pageSize: 100, cursor });

for (const contact of page.items) {
  // procesar cada contacto
  total++;
}

cursor = page.nextCursor;
} while (cursor);

console.log(`Contactos recorridos: ${total}`);
```

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `pageSize` | `number` | Tamaño de página, entre 1 y 100. Default 20. |
| `cursor` | `string \| null` | El `nextCursor` de la página anterior. Omitir en la primera llamada. |

Si consumes la API REST directamente, los mismos parámetros van como query string en `GET /api/contact`:

```
GET /api/contact?workspaceId={id}&pageSize=100
GET /api/contact?workspaceId={id}&pageSize=100&continuationToken={cursor URL-encoded}
```

La respuesta incluye `data.continuationToken` (el cursor de la siguiente página, `null` al terminar) y `data.data` (los contactos). El cursor debe enviarse URL-encoded (`encodeURIComponent`).

Ten en cuenta el [límite de la API](https://developers.plazbot.com/sdk/rate-limits) (120 req/min por workspace): con `pageSize=100`, recorrer 50.000 contactos son 500 llamadas.

---

### Obtener Contacto por ID

```ts
const contact = await plazbot.contact.getContact("contact-id");
console.log(contact.name, contact.email);
```

---

### Buscar por Teléfono

```ts
const results = await plazbot.contact.searchByPhone("51912345678");
```

---

### Buscar por Email

```ts
const results = await plazbot.contact.searchByEmail("juan@ejemplo.com");
```

---

### Actualizar Contacto

```ts
const updated = await plazbot.contact.updateContact({
id: "contact-id",
name: "Juan Perez Actualizado",
tags: ["lead", "premium", "web"]
});
```

---

### Eliminar Contactos

Elimina uno o multiples contactos por sus IDs.

```ts
await plazbot.contact.deleteContacts([
"contact-id-1",
"contact-id-2"
]);
```

---

### Campos del Contacto

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `id` | `string` | Identificador único |
| `name` | `string` | Nombre del contacto |
| `cellphone` | `string` | Número de teléfono |
| `email` | `string` | Correo electrónico |
| `tags` | `string[]` | Etiquetas |
| `stage` | `string` | Etapa en el pipeline |
| `owner` | `string` | Propietario del contacto |
| `createdAt` | `string` | Fecha de creación |
| `updatedAt` | `string` | Fecha de actualización |

---

### TypeScript

El SDK exporta los tipos para autocompletado:

```ts
import type {
ContactData,
CreateContactParams,
UpdateContactParams
} from 'plazbot';
```

> **Tip:** Combina el módulo de Contact con el de Message para enviar plantillas de WhatsApp a contactos de tu base de datos de forma automatizada.