> ## 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.

# Buscar por Teléfono

> Busca una conversación por número de teléfono

## Parámetros de Path

<ParamField path="phone" type="string" required>
  Número de teléfono en formato E.164 (ej: `+5215512345678`)
</ParamField>

<Tip>
  El número se normaliza automáticamente. Puedes enviar `5215512345678`, `+5215512345678`, o `521 55 1234 5678`.
</Tip>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.whaapy.com/conversations/v1/by-phone/+5215512345678" \
    -H "Authorization: Bearer wha_xxxxx"
  ```

  ```javascript Node.js theme={null}
  const phone = '+5215512345678';
  const response = await fetch(
    `https://api.whaapy.com/conversations/v1/by-phone/${encodeURIComponent(phone)}`,
    {
      headers: { 'Authorization': 'Bearer wha_xxxxx' }
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests
  from urllib.parse import quote

  phone = '+5215512345678'
  response = requests.get(
      f'https://api.whaapy.com/conversations/v1/by-phone/{quote(phone, safe="")}',
      headers={'Authorization': 'Bearer wha_xxxxx'}
  )
  data = response.json()
  ```

  ```php PHP theme={null}
  $phone = urlencode('+5215512345678');
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.whaapy.com/conversations/v1/by-phone/{$phone}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer wha_xxxxx"
    ],
  ]);

  $response = curl_exec($curl);
  $data = json_decode($response, true);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phoneNumber": "+5215512345678",
      "contactName": "Juan Pérez",
      "profilePictureUrl": "https://...",
      "lastMessageAt": "2026-01-29T10:30:00Z",
      "lastMessagePreview": "Hola, ¿tienen disponibilidad?",
      "unreadCount": 2,
      "status": "active",
      "contact": {
        "id": "uuid",
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com",
        "phoneNumber": "+5215512345678",
        "avatarUrl": null,
        "tags": ["cliente-nuevo"],
        "customFields": {},
        "funnelStage": {
          "id": "uuid",
          "name": "Interesado",
          "color": "#3B82F6",
          "position": 1
        }
      },
      "settings": {
        "aiEnabled": true,
        "aiMode": "auto",
        "aiPausedUntil": null,
        "pausedBy": null
      },
      "createdAt": "2026-01-28T08:00:00Z",
      "updatedAt": "2026-01-29T10:30:00Z"
    }
  }
  ```
</ResponseExample>

## Errores

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "error": "Not found",
    "message": "Conversación no encontrada para este número de teléfono"
  }
  ```
</ResponseExample>

<Info>
  Este endpoint es útil para integraciones donde tienes el número de teléfono pero no el ID de la conversación. Por ejemplo, cuando recibes un webhook de tu CRM con el teléfono del cliente.
</Info>

## Casos de uso

<AccordionGroup>
  <Accordion title="Sincronizar desde CRM">
    Cuando tu CRM te notifica sobre un cliente, busca su conversación por teléfono:

    ```javascript theme={null}
    // Webhook de HubSpot/Salesforce
    const phoneFromCRM = '+5215512345678';
    const conversation = await fetch(
      `https://api.whaapy.com/conversations/v1/by-phone/${encodeURIComponent(phoneFromCRM)}`,
      { headers: { 'Authorization': 'Bearer wha_xxxxx' } }
    ).then(r => r.json());

    if (conversation.data) {
      console.log('Conversación encontrada:', conversation.data.id);
    }
    ```
  </Accordion>

  <Accordion title="Verificar si existe conversación">
    Antes de iniciar una nueva conversación, verifica si ya existe una:

    ```javascript theme={null}
    async function getOrCreateConversation(phone) {
      // Primero buscar existente
      const existing = await fetch(
        `https://api.whaapy.com/conversations/v1/by-phone/${encodeURIComponent(phone)}`,
        { headers: { 'Authorization': 'Bearer wha_xxxxx' } }
      ).then(r => r.ok ? r.json() : null);
      
      if (existing?.data) {
        return existing.data;
      }
      
      // Si no existe, enviar mensaje para crear
      const newMessage = await fetch('https://api.whaapy.com/messages/v1', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer wha_xxxxx',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          to: phone,
          type: 'template',
          template: { name: 'hello_world', language: 'es_MX' }
        })
      }).then(r => r.json());
      
      return newMessage.data;
    }
    ```
  </Accordion>
</AccordionGroup>