curl -X GET "https://api.whaapy.com/conversations/v1/by-phone/+5215512345678" \
-H "Authorization: Bearer wha_xxxxx"
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();
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()
$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);
{
"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"
}
}
Conversaciones
Buscar por Teléfono
Busca una conversación por número de teléfono
GET
/
conversations
/
v1
/
by-phone
/
{phone}
curl -X GET "https://api.whaapy.com/conversations/v1/by-phone/+5215512345678" \
-H "Authorization: Bearer wha_xxxxx"
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();
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()
$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);
{
"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
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"
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();
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()
$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);
{
"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
Sincronizar desde CRM
Sincronizar desde CRM
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);
}
Verificar si existe conversación
Verificar si existe conversación
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;
}
Was this page helpful?