Skip to main content
GET
/
conversations
/
v1
/
by-phone
/
{phone}
curl -X GET "https://api.whaapy.com/conversations/v1/by-phone/+5215512345678" \
  -H "Authorization: Bearer wha_xxxxx"

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

​
Parámetros de Path

​
phone
string
required
Número de teléfono en formato E.164 (ej: +5215512345678)
El número se normaliza automáticamente. Puedes enviar 5215512345678, +5215512345678, o 521 55 1234 5678.
curl -X GET "https://api.whaapy.com/conversations/v1/by-phone/+5215512345678" \
  -H "Authorization: Bearer wha_xxxxx"

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

​
Errores

{
  "error": "Not found",
  "message": "Conversación no encontrada para este número de teléfono"
}
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.

​
Casos de uso

Cuando tu CRM te notifica sobre un cliente, busca su conversación por teléfono:
// 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);
}
Antes de iniciar una nueva conversación, verifica si ya existe una:
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;
}