CRM-Endpunkte
Verbinde WAzion mit deinem externen CRM oder ERP, damit die KI und das Seitenpanel auf Kundendaten, Bestellungen und Produkte aus deinem System zugreifen können.
Was sind CRM-Endpunkte?
Die CRM-Endpunkte ermöglichen es WAzion, Informationen aus deinem externen System (CRM, ERP, eigene Datenbank) abzufragen. Im Gegensatz zu den KI-Funktionen (bei denen die KI entscheidet, wann sie aufgerufen werden), werden diese Endpunkte automatisch aufgerufen, wenn der Agent ein Gespräch eröffnet oder nach Informationen sucht.
Für das Seitenpanel
Zeigt Kundendaten neben dem Gespräch an (Bestellungen, Verlauf, Kontaktinformationen).
Für die KI
Gib Anfangsinformationen über den Kunden an, damit die KI mit relevanten Informationen antworten kann.
1 sidePanel_CustomerInfo
Stellt Kundeninformationen bereit, die in der Seitenleiste der Erweiterung angezeigt werden, wenn der Agent ein Gespräch öffnet.
Gesendete Parameter
| phone | Kundentelefonnummer (E.164) |
| token | Authentifizierungstoken |
| relatedphones | Verwandte Telefone (Array) |
Erwartete Antwort
{
"found": true,
"customers": [
{
"name": "Juan García",
"email": "juan@email.com",
"phone": "+34612345678",
"shopUrl": "https://tucrm.com/c/123",
"ordersCount": 5,
"totalSpent": 450.00,
"totalRefunded": 0,
"state": "VIP - Activo",
"orders": [...],
"abandonedCarts": [...]
}
]
}
Hinweis: Sie können “customer“ (Objekt) oder “customers“ (Array) verwenden, um mehrere Kunden zu unterstützen. Gibt IMMER HTTP 200 zurück, auch wenn kein Kunde gefunden wird (verwenden Sie “found“: false).
📦 Komplette Antwortstruktur anzeigen (Bestellungen, Artikel, Sendungsverfolgung, aufgegebene Warenkörbe)
Vollständige JSON-Struktur mit allen unterstützten Feldern:
{
"found": true,
"customers": [
{
"// Datos básicos del cliente"
"name": "Juan García López",
"email": "juan@email.com",
"phone": "+34612345678",
"shopUrl": "https://tu-crm.com/clientes/123",
"ordersCount": 15,
"totalSpent": 1250.50,
"totalRefunded": 50.00,
"totalDiscounts": 25.00,
"state": "Cliente VIP",
"// Array de pedidos"
"orders": [
{
"name": "#ORD-2025-001",
"date": "2025-01-10T14:30:00Z",
"amount": 129.99,
"netAmount": 104.99,
"totalRefunded": 25.00,
"totalDiscounts": 10.00,
"currency": "EUR",
"cancelled": false,
"shopUrl": "https://tu-crm.com/pedidos/1234",
"note": "Entregar por la tarde",
"// Items del pedido"
"items": [
{
"title": "Camiseta Premium Azul - Talla L",
"quantity": 2,
"currentQuantity": 2,
"amount": 59.98,
"originalAmount": 59.98,
"discountedAmount": 59.98,
"discount": 0,
"refundedQuantity": 0,
"refundedAmount": 0,
"status": "active" // active | partially_refunded | fully_refunded
}
],
"// Tracking de envíos"
"tracking": [
{
"number": "ES123456789012",
"company": "SEUR",
"url": "https://www.seur.com/tracking/...",
"displayStatus": "Entregado"
}
]
}
],
"// Carritos abandonados"
"abandonedCarts": [
{
"date": "2025-01-14T18:45:00Z",
"url": "https://tu-tienda.com/cart/recover/abc123",
"items": [
{
"title": "Zapatillas Running Pro",
"quantity": 1,
"amount": 129.99
}
]
}
]
}
]
}
Kundenfelder:
| Feld | Artículo | Erforderlich |
|---|---|---|
| name | string | Ja |
| string | Ja | |
| phone | string | Ja |
| shopUrl | string | No |
| ordersCount | number | Ja |
| totalSpent | number | Ja |
| totalRefunded | number | No |
| totalDiscounts | number | No |
| state | string | Ja |
| orders | array | No |
| abandonedCarts | array | No |
Bestellfelder (Order):
| Feld | Artículo | Beschreibung |
|---|---|---|
| name | string | Bestell-ID/Bestellnummer |
| date | string | ISO-8601-Datum |
| amount | number | Gesamtbestellwert |
| netAmount | number | Nettobetrag (nach Rückerstattungen) |
| currency | string | Währungscode (EUR, USD...) |
| cancelled | boolean | wahr, wenn es storniert ist |
| shopUrl | string | URL zur Bestellung in deinem System |
| note | string | Bestellnotiz |
| items | array | Bestellte Produkte |
| tracking | array | Versand/Sendungsverfolgung |
Felder des Artikels:
| Feld | Artículo | Beschreibung |
|---|---|---|
| title | string | Produktname |
| quantity | number | Bestellte Menge |
| currentQuantity | number | Aktuelle Menge (nach Rückerstattungen) |
| amount | number | Gesamtpreis des Artikels |
| refundedQuantity | number | Erstattete Einheiten |
| refundedAmount | number | Erstatteter Betrag |
| status | string | active | partially_refunded | fully_refunded |
Tracking-Felder:
| Feld | Artículo | Beschreibung |
|---|---|---|
| number | string | Sendungsnummer |
| company | string | Versandunternehmen |
| url | string | Tracking-URL |
| displayStatus | string | Lesbarer Status (Zugestellt, Unterwegs...) |
Übersetzungs-Labels (UI)
Damit die Erweiterung die Texte in der richtigen Sprache anzeigt, fügen Sie das Objekt „labels“ mit den Übersetzungen ein:
{
"found": true,
"customer": { ... },
"labels": {
"label_languages": "es",
"customer_info": "Información del Cliente",
"name": "Nombre",
"email": "Email",
...
}
}
Siehe vollständige Tabelle der verfügbaren Etiketten
| Key | Default (ES) | Beschreibung |
|---|---|---|
| label_languages | "es" | Etikettensprache. Wenn sie von der Sprache des Shops abweicht, übersetzt WAzion sie automatisch. |
| customer_info | "Información del Cliente" | Kundensektionsüberschrift |
| name | "Nombre" | Namensetikett |
| "Email" | E-Mail-Tag | |
| phone | "Teléfono" | Telefonetikett |
| orders_count | "Pedidos" | Auftragszähler |
| total_spent | "Total gastado" | Gesamtausgaben |
| total_refunded | "Total reembolsado" | Rückerstattungen |
| discounts | "Descuentos" | Rabatte |
| customer_state | "Estado" | Kundenstatus |
| recent_orders | "Pedidos recientes" | Bestelltitel |
| order | "Pedido" | Einzelbestellung |
| orders | "Pedidos" | Bestellungen |
| order_number | "Nº de pedido" | Bestellnummer |
| date | "Fecha" | Datum |
| amount | "Importe" | Betrag |
| net_amount | "Importe neto" | Nettobetrag |
| subtotal | "Subtotal" | Zwischensumme |
| discount | "Descuento" | Einzelrabatt |
| refund | "Reembolso" | Erstattung |
| refunded | "Reembolsado" | Erstattetes Abzeichen |
| cancelled | "Cancelado" | Abzeichen storniert |
| cancel_reason | "Motivo cancelación" | Stornierungsgrund |
| items | "Artículos" | Produkte/Artikel |
| item_status | "Estado artículo" | Artikelzustand |
| quantity | "Cantidad" | Menge |
| original_quantity | "Cantidad original" | Ursprüngliche Menge |
| current_quantity | "Cantidad actual" | Aktuelle Menge |
| sku | "SKU" | SKU |
| shipments | "Envíos" | Versand |
| shipping | "Envío" | Einzelversand |
| tracking_number | "Nº seguimiento" | Sendungsnummer |
| no_shipping_info | "Sin información de envío" | Ohne Versand |
| order_note | "Nota del pedido" | Bestellnotizen |
| fully_refunded | "Reembolsado completamente" | Artikel 100 % erstattet |
| partially_refunded | "Reembolsado parcialmente" | Teilweise erstatteter Posten |
| active | "Activo" | Aktiver Zustand |
| abandoned_carts | "Carrito/s abandonado/s" | Verlassene Einkaufswagen |
| copy_link | "Copiar enlace" | Kopiertaste |
| view_customer | "Ver perfil del cliente" | Kunden anzeigen Schaltfläche |
| view_profile | "Ver perfil" | Profil ansehen Schaltfläche |
| remove_assignment | "Quitar asignación" | Entfernen-Schaltfläche |
| not_found | "Cliente no encontrado" | Nachricht nicht gefunden |
| no_orders | "Sin pedidos" | Keine Bestellungen |
| error | "Error" | Fehlervorsatz |
| Kundenzustände | ||
| state_no_orders | "Sin pedidos" | Status: keine Bestellungen |
| state_conflictive | "Conflictivo" | Status: konfliktträchtig |
| state_processing | "Procesando" | Status: wird verarbeitet |
| state_new_orders | "Pedidos nuevos" | Status: neue Bestellungen |
| state_recent_orders | "Pedidos recientes" | Status: letzte Bestellungen |
| state_old_orders | "Pedidos antiguos" | Status: alte Bestellungen |
Automatische Übersetzung: Wenn du Labels in einer Sprache sendest (z.B. Englisch mit label_languages: “en“) und der Shop in einer anderen Sprache eingestellt ist (z.B. Spanisch), übersetzt WAzion automatisch alle Labels. So kannst du dein CRM in nur einer Sprache pflegen.
2 ai_CustomerInitialInfo
Geben Sie der KI einen anfänglichen Kontext zum Kunden. Dieser Text wird in die Eingabeaufforderung der KI aufgenommen, damit sie mit relevanten Informationen zum Kunden antworten kann.
Gesendete Parameter
| phone | Kundentelefonnummer (E.164) |
| token | Authentifizierungstoken |
| relatedphones | Verwandte Telefone (Array) |
| order | Erwähnte Bestellnummer (optional) |
| E-Mail des Kunden (optional) | |
| test | true“ wenn es ein Test ist |
Erwartete Antwort
{
"found": true,
"info": "Cliente: Juan García.
VIP: Sí. Total pedidos: 5.
Último pedido: #12345 (15/01/2024)
Estado: Entregado.
Productos frecuentes: Zapatos, Camisetas.
ALERTA: Cliente alérgico al gluten."
}
Wichtig: Das Feld “info“ ist freier Text, den die KI als Kontext lesen wird. Es enthält Einkaufsverlauf, Vorlieben, wichtige Warnhinweise (Allergien, frühere Probleme), Kundenstatus, bevorzugte Zahlungs-/Versandmethode usw.
3 sidePanel_CustomerFindToJoin
Ermöglicht die Suche nach Kunden in deinem System, um sie mit einem WhatsApp-Gespräch zu verknüpfen. Nützlich, wenn der Kunde von einer anderen als der registrierten Nummer schreibt.
Gesendete Parameter
| query | Suchtext |
| token | Authentifizierungstoken |
| phone | Aktuelle Gesprächstelefonnummer |
| relatedphones | Bereits zugeordnete Telefone (Array, zum Ausschließen) |
Erwartete Antwort
{
"customers": [
{
"id": "cust_123",
"name": "Juan García",
"email": "juan@email.com",
"phone": "+34612345678"
},
{
"id": "cust_456",
"name": "Juan Martínez",
"email": "juanm@email.com",
"phone": "+34687654321"
}
]
}
Hinweis: Du kannst “customers“ oder “results“ als Namen des Arrays verwenden. Das Feld “phone“ jedes Kunden ermöglicht es WAzion, das Gespräch automatisch zu verknüpfen.
4 search_Products
Ermöglicht die Suche nach Produkten in Ihrem externen Katalog. Die Ergebnisse werden im Seitenbereich angezeigt und der Agent kann sie mit dem Kunden teilen. Die KI kann auch nach Produkten suchen, um Fragen zu beantworten.
Hinweis für CRM Custom: WAzion fungiert als transparenter Proxy für diesen Endpunkt. Die Antwort deines CRM wird unverändert direkt an die Erweiterung weitergegeben. Du musst die vollständige dokumentierte Struktur implementieren, wenn du alle Funktionen nutzen möchtest. Die angereicherten Felder (target_locale, title_copy, raw, usw.) werden nur automatisch für Shopify-Shops generiert.
Gesendete Parameter
| Parameter | Artículo | Beschreibung |
|---|---|---|
| q | string | Suchtext (mindestens 2 Zeichen) |
| token | string | Authentifizierungstoken des Shops |
| phone | string | Kundentelefonnummer (E.164) – für länderspezifische URLs |
| format | string | ai“, wenn die KI nach Produkten sucht (ändert die Antwortstruktur) |
| target_locale | string | Vom Telefon des Kunden erkannte Sprache (z.B. “es“, “de“, “fr“) |
| test | boolean | true“, wenn es sich um einen Verbindungstest handelt |
Neu: Zielort - WAzion erkennt automatisch die Sprache des Kunden anhand der Vorwahl seiner Telefonnummer. Zum Beispiel +34... → “es“, +49... → “de“. Verwenden Sie diesen Parameter, um Produkte in der richtigen Sprache zurückzugeben.
Antwort im NORMAL-Format (Seitenleiste)
Wenn der Agent Produkte über das Panel sucht. Enthält Felder zum Kopieren/Teilen.
{
"http_status": 200,
"count": 1,
"products": [
{
"title": "Camiseta Premium",
"title_copy": "Premium T-Shirt",
"handle": "camiseta-premium",
"description": "Descripción truncada a 500 chars...",
"sku": "CAM-001",
"image": "https://proxy/imagen.jpg",
"url": "https://tutienda.es/products/camiseta-premium",
"variants": [
{
"id": "12345678",
"title": "M / Rojo",
"title_copy": "M / Red",
"has_custom_title": true,
"sku": "CAM-001-M-RED",
"image": "https://proxy/variante.jpg",
"url": "https://tutienda.es/products/camiseta-premium?variant=12345678"
}
]
}
],
"target_locale": "en",
"raw": { ... }
}
Antwort im AI-Format (wenn format=“ai“)
Wenn die KI nach Produkten sucht. Vereinfachte Struktur ohne Kopierfelder, vollständige Beschreibung.
{
"count": 1,
"products": [
{
"title": "Premium T-Shirt",
"handle": "camiseta-premium",
"description": "Descripción COMPLETA sin truncar para contexto IA...",
"sku": "CAM-001",
"url": "https://tutienda.es/products/camiseta-premium",
"variants": [
{
"id": "12345678",
"title": "M / Red",
"sku": "CAM-001-M-RED",
"url": "https://tutienda.es/products/camiseta-premium?variant=12345678"
}
]
}
],
"locale": "en"
}
Alle Produktfelder anzeigen
| Feld | Normal | KI | Beschreibung |
|---|---|---|---|
| title | Original | Übersetzt | Produkttitel |
| title_copy | Übersetzt | - | Titel zum Kopieren (Kundensprache) |
| handle | ✓ | ✓ | Produkt-Slug |
| description | 500 Zeichen | Vervollständigen | Beschreibung (gereinigtes HTML) |
| sku | ✓ | ✓ | SKU der ersten Variante |
| image | ✓ | - | Bild-URL (kann über einen Proxy laufen) |
| url | ✓ | ✓ | Produkt-URL |
| variants | ✓ | ✓ | Array von Varianten |
Variantenfelder anzeigen
| Feld | Normal | KI | Beschreibung |
|---|---|---|---|
| id | ✓ | ✓ | Varianten-ID |
| title | Original | Übersetzt | Variantenbezeichnung (z.B.: “M / Rot“) |
| title_copy | Übersetzt | - | Titel zum Kopieren (Kundensprache) |
| has_custom_title | ✓ | - | true, wenn es einen benutzerdefinierten Titel hat (nicht “Standardtitel“) |
| sku | ✓ | ✓ | Variante SKU |
| image | ✓ | - | Spezifisches Bild der Variante (oder des Produkts, falls keine vorhanden ist) |
| url | ✓ | ✓ | URL mit ?variant=ID |
Wurzelantwortfelder anzeigen
| Feld | Normal | KI | Beschreibung |
|---|---|---|---|
| http_status | ✓ | - | HTTP-Antwortcode |
| count | ✓ | ✓ | Anzahl gefundener Produkte |
| products | ✓ | ✓ | Produktarray |
| target_locale | ✓ | - | Für Übersetzungen verwendete Gebietsschema |
| locale | - | ✓ | Verwendeter Gebietsschema (nur AI-Format) |
| raw | ✓ | - | Rohantwort der Quelle (Debug) |
🌍 Länderspezifische URLs
Der Parameter phone enthält die Telefonnummer des Kunden (E.164). Verwenden Sie ihn, um sein Land zu erkennen und angepasste URLs zurückzugeben:
- Länderspezifische Domains (tutienda.es, tutienda.de, tutienda.fr)
- Routen mit Sprachpräfix (/es/, /de/, /fr/)
- Locale-Parameter (?locale=es_ES)
- Shopify-spezifische Märkte
Beispiel: Wenn die Telefonnummer mit +34 (Spanien) beginnt, URLs mit der Domain .es oder /es/ zurückgeben.
5 globalSearch
Globale Kundensuche für den schwebenden Sucher der Erweiterung. Ermöglicht die Suche nach Name, E-Mail, Telefon oder Bestellnummer.
Gesendete Parameter
| Parameter | Artículo | Beschreibung |
|---|---|---|
| query | string | Suchtext (mindestens 2 Zeichen) |
| token | string | Authentifizierungstoken des Shops |
Erwartete Antwort
{
"found": true,
"customers": [
{
"id": "cust_123",
"name": "Juan García López",
"email": "juan.garcia@email.com",
"phone": "+34612345678",
"customerUrl": "https://tucrm.com/clientes/123",
"orders": [
{
"number": "#ORD-1234",
"url": "https://tucrm.com/pedidos/1234"
},
{
"number": "#ORD-1233",
"url": "https://tucrm.com/pedidos/1233"
}
]
}
]
}
Felder jedes Kunden
| Feld | Artículo | Erforderlich | Beschreibung |
|---|---|---|---|
| id | string | Ja | Eindeutige Kundennummer in deinem System |
| name | string | Ja | Vollständiger Name des Kunden |
| string | Ja | Kunden-E-Mail | |
| phone | string | Ja | Kundentelefon (E.164 bevorzugt, z. B.: +34612345678) |
| customerUrl | string | Nein | URL, um den Kunden in deinem CRM zu sehen (wird als anklickbarer Link angezeigt) |
| orders | array | Nein | Array mit den letzten Bestellungen (maximal 3) |
Felder jeder Bestellung (orders[])
| Feld | Artículo | Erforderlich | Beschreibung |
|---|---|---|---|
| number | string | Ja | Bestellnummer (z. B. “#ORD-1234“) |
| url | string | Nein | URL, um die Bestellung in deinem System anzusehen |
Wichtige Hinweise
- • Das Feld
phoneist erforderlich, damit der Agent das Gespräch mit diesem Kunden eröffnen kann. - • Maximal 15 Ergebnisse werden dem Benutzer angezeigt (automatisch begrenzt).
- • Telefonduplikate werden automatisch gelöscht.
- • Wenn
customerUrlvorhanden ist, wird der Kundenname ein anklickbarer Link sein. - • Die Bestellungen werden dem Kunden darunter als einzelne Links angezeigt.
Technische Spezifikationen
Zeitüberschreitungen
| globalSearch | 5s |
| Andere Endpunkte | 10s |
| Verbindungszeitüberschreitung | 5s |
| Wiederholungen | Nein |
HTTP-Methoden
| Konfigurierbar | GET / POST |
| Body (POST) | JSON / Form |
| Parameter (GET) | Query string |
Anforderungen
- HTTPS verpflichtend
- Gültige JSON-Antwort
- HTTP 200 immer (found:false verwenden, wenn keine Daten vorhanden sind)
Unterschied zu KI-Funktionen
Die CRM-Endpunkte werden bei einem Fehler nicht automatisch erneut aufgerufen. Sie werden in Echtzeit aufgerufen, während der Agent arbeitet, daher müssen sie schnell antworten. Wenn sie ausfallen, erscheinen die Informationen einfach nicht.
Arten der Authentifizierung
Beispiel-URL (GET + Abfrageauthentifizierung)
// WAzion llamará:
https://tu-api.com/customer
?phone=+34612345678
&token=tu-token-secreto
&relatedphones=["+34698765432"]
&test=false
Beispiel für die Umsetzung
<?php
// Endpoint: /api/customer-info
header('Content-Type: application/json');
// Obtener parámetros (soporta GET y POST)
$input = json_decode(file_get_contents('php://input'), true) ?? $_GET;
$phone = $input['phone'] ?? '';
$token = $input['token'] ?? '';
$relatedPhones = $input['relatedphones'] ?? [];
$order = $input['order'] ?? '';
$isTest = ($input['test'] ?? '') === 'true';
// Verificar token
if ($token !== 'tu-token-secreto') {
echo json_encode(['found' => false, 'error' => 'No autorizado']);
exit;
}
// Si es test, devolver datos de ejemplo
if ($isTest) {
echo json_encode([
'found' => true,
'customers' => [[
'name' => 'Cliente de Prueba',
'email' => 'test@example.com',
'phone' => '+34612345678',
'shopUrl' => 'https://tucrm.com/cliente/123',
'ordersCount' => 3,
'totalSpent' => 150.00,
'state' => 'Activo',
'orders' => []
]]
]);
exit;
}
// Buscar por teléfono principal + relacionados
$allPhones = array_merge([$phone], $relatedPhones);
$customers = buscarClientesPorTelefonos($allPhones);
echo json_encode([
'found' => !empty($customers),
'customers' => $customers
]);
const express = require('express');
const app = express();
app.use(express.json());
const SECRET_TOKEN = 'tu-token-secreto';
app.all('/api/customer-info', async (req, res) => {
// Soporta GET y POST
const params = { ...req.query, ...req.body };
const { phone, token, relatedphones = [], order, test } = params;
// Verificar token
if (token !== SECRET_TOKEN) {
return res.json({ found: false, error: 'No autorizado' });
}
// Datos de test
if (test === 'true') {
return res.json({
found: true,
customers: [{
name: 'Cliente de Prueba',
email: 'test@example.com',
phone: '+34612345678',
shopUrl: 'https://tucrm.com/cliente/123',
ordersCount: 3,
totalSpent: 150.00,
state: 'Activo',
orders: []
}]
});
}
// Buscar clientes
const allPhones = [phone, ...relatedphones];
const customers = await buscarClientesPorTelefonos(allPhones);
res.json({ found: customers.length > 0, customers });
});
app.listen(3000);
from flask import Flask, request, jsonify
app = Flask(__name__)
SECRET_TOKEN = 'tu-token-secreto'
@app.route('/api/customer-info', methods=['GET', 'POST'])
def customer_info():
# Soporta GET y POST
params = {**request.args, **request.get_json(silent=True) or {}}
phone = params.get('phone', '')
token = params.get('token', '')
related_phones = params.get('relatedphones', [])
is_test = params.get('test') == 'true'
# Verificar token
if token != SECRET_TOKEN:
return jsonify({'found': False, 'error': 'No autorizado'})
# Datos de test
if is_test:
return jsonify({
'found': True,
'customers': [{
'name': 'Cliente de Prueba',
'email': 'test@example.com',
'phone': '+34612345678',
'shopUrl': 'https://tucrm.com/cliente/123',
'ordersCount': 3,
'totalSpent': 150.00,
'state': 'Activo',
'orders': []
}]
})
# Buscar clientes
all_phones = [phone] + related_phones
customers = buscar_clientes_por_telefonos(all_phones)
return jsonify({'found': len(customers) > 0, 'customers': customers})
Änderungsverlauf
sidePanel_CustomerInfo übersetzt jetzt automatisch alle Bezeichnungen, wenn label_languages sich von der Geschäftssprache unterscheidet. Sie können Ihr CRM in einer einzigen Sprache (z.B. Englisch) führen und WAzion kümmert sich um die Übersetzungen.
WAzion sendet jetzt die vom Kunden erkannte Sprache (basierend auf der Vorwahl seiner Telefonnummer) als Parameter target_locale. Nützlich, um Produkte in der richtigen Sprache des Kunden zurückzugeben.