Byg en integration fra ende til anden

Denne guide gennemgår alt, hvad du behøver for at køre Your AI Connector fra din egen kode, uden nogensinde at åbne dashboardet. Når du er færdig, har du bygget en minimal integration, der:

Godkender med en API-nøgle
Opretter en AI-agent og konfigurerer dens assistentadfærd
Forbinder en beskedkanal (vi bruger WhatsApp Web som eksempel) og peger den mod agenten
Importerer kontakter
Sender og læser beskeder
Læser analyse
Abonnerer på webhooks for begivenheder i realtid

Hvert trin linker til den fulde ressourceguide, så du kan dykke ned i detaljerne, når du har brug for det. Denne side er kortet; ressourceguiderne er terrænet.

Før du starter. API-adgang er en betalt funktion. Hvis dit abonnement ikke inkluderer det, returnerer hver anmodning 403. Se API-adgang for at bekræfte, at det er aktiveret, og Autentificering for alle måder at sende din nøgle på.

Alle stier herunder er relative til basis-URL’en:

https://api.youraiconnector.com/v1

Trin 1 — Få en API-nøgle og foretag din første anmodning

Din API-nøgle findes i appen under Indstillinger → Integrationer → API-nøgle — dens egen sektion under Integrationer, adskilt fra Webhooks, som kun vises, når API-adgang er inkluderet i planen. Generér en, kopiér den, og gem den et sikkert sted (et server-side hemmelighedslager eller en miljøvariabel — aldrig i browserkode). Fuldstændige instruktioner findes i API-adgang.

Når du har en nøgle, skal du bekræfte, at den virker ved at kalde health-endpointet. Der er flere måder at sende nøglen på; den enkleste er ?apiKey=-forespørgselsparameteren, men til rigtig kode bør du foretrække X-API-Key-headeren, så nøglen aldrig ender i serverlogfiler eller browserhistorik.

cURL

curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"

JavaScript

const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }

Python

import requests

BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json())  # { "success": true, ... }

Hvert succesfuldt svar er pakket ind i den samme konvolut — et success: true-felt plus resultatdataene. Fejl returnerer success: false med en error-besked og en error_code. Se Fejl & Sidetal for den fulde liste og for hvordan liste-endpoints paginerer med ?limit og ?cursor.

Hastighedsbegrænsning. Autentificerede anmodninger er begrænset til 300 pr. minut (med et højere loft på 1.200 pr. minut pr. konto). Overskridelse returnerer 429; vent og prøv igen.

Trin 2 — Opret en AI-agent

En AI-agent er den enhed, der indeholder din assistents adfærd: dens instruktioner, dens mål, dens aktive timer og hvordan den taler med kontakter. Det er den, der besvarer en samtale, så dette er det naturlige første skridt at tage.

Opret en med POST /agents. name er det eneste felt, der er værd at sende med det samme; alt andet kan indstilles med bot-config-kaldet herunder.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound WhatsApp Leads",
    "language": "en"
  }'

JavaScript

const res = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Inbound WhatsApp Leads",
    language: "en",
  }),
});
const { agent_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/agents",
    headers=HEADERS,
    json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]

En succesfuld oprettelse returnerer 201 med det nye ID:

{
  "success": true,
  "agent_id": "abc123agent"
}

Gem agent_id — du skal bruge den, når du dirigerer kanaler.

Konfigurer assistenten

PUT /agents/{agentId}/bot-config indstiller assistentens adfærd. Den fletter de felter, du sender, ind i den eksisterende konfiguration, så alt, hvad du udelader, bevares:

curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
    "goal": "Book a discovery call.",
    "ai_speed": "balanced"
  }'

Indstil aktive timer med PUT /agents/{agentId}/active-hours, så assistenten kun svarer i åbningstiden; uden for disse tidsrum svarer den ikke automatisk.

Vidensbase. For at få assistenten til at svare ud fra dit eget indhold, skal du vedhæfte ofte stillede spørgsmål (FAQ). Se FAQ-guiden.

Legacy: klassiske kampagner. Konti, der stadig har en Kampagner-side, opretter den samme assistentadfærd på en kampagne i stedet (POST /campaigns med et type og et bot objekt, derefter PUT /campaigns/{campaignId}/bot-config). Den fulde liste over kampagnefelter og livscykluskontroller findes i Kampagneguiden. Hvis du bygger noget nyt, skal du oprette en agent.

Trin 3 — Tilslut en kanal

En agent har brug for en måde at sende og modtage beskeder på. Syv forbindelsesflows kan styres fra API’et: WhatsApp Business, WhatsApp Web, Instagram og Messenger sammen (ét delt Meta-flow), personlige Instagram-konti, Telegram, LINE og Viber. De resterende kanaler — herunder SMS, e-mail, chat-widget og brugerdefinerede kanaler — opsættes i dashboardet frem for via REST, og når de først er forbundet, fungerer besked-, kontakt- og dirigerings-endpoints på nøjagtig samme måde. GET /channels er den live kilde til sandhed for, hvad en given konto faktisk har forbundet:

curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"

Det fulde sæt af flows til tilslutning/frakobling for hver kanal er dokumenteret i Kanalguiden. Nedenfor gennemgår vi WhatsApp Web fra start til slut, da det viser det mest interessante mønster: et QR-kode-parringsflow, som din wrapper skal rendere og polle.

Gennemgang af eksempel: parring af WhatsApp Web via QR-kode

Parring af WhatsApp Web er en proces i tre trin — start, hent QR-koden, pol indtil forbindelse er oprettet.

1. Start parringssessionen. Angiv det nummer, du vil tilslutte, i E.164-format.

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});

requests.post(
    f"{BASE}/channels/whatsapp-web/connections",
    headers=HEADERS,
    json={"phone_number": "+15551230000"},
)

2. Hent QR-koden og vis den til brugeren. Pol dette hvert 10.–15. sekund. Svaret indeholder den rå qr_code-nyttelast (render den selv som et QR-billede) og en qr_data_url, der er klar til visning.

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@abc...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}

I din wrappers brugerflade skal du indsætte qr_data_url direkte i et <img src="...">-element og bede brugeren om at scanne det fra WhatsApp → Tilknyttede enheder på deres telefon. Hvis QR-koden udløber (et 410-svar), skal du starte forfra fra trin 1 for at få en ny.

3. Pol status, indtil forbindelsen er oprettet. Når brugeren har scannet, skal du fortsætte med at polle status-endepunktet, indtil det rapporterer connected (tjenesten kan også rapportere open). Betragt disconnected og not_initialized som terminale fejl.

import time

PHONE = "+15551230000"
while True:
    res = requests.get(
        f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
        headers=HEADERS,
    )
    status = res.json()["status"]
    if status in ("connected", "open"):
        print("Connected!")
        break
    if status in ("disconnected", "not_initialized"):
        raise RuntimeError(f"Pairing failed: {status}")
    time.sleep(5)

async function waitForConnection(phone) {
  while (true) {
    const res = await fetch(
      `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
      { headers }
    );
    const { status } = await res.json();
    if (status === "connected" || status === "open") return;
    if (status === "disconnected" || status === "not_initialized") {
      throw new Error(`Pairing failed: ${status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

Bemærk. Hvert tilsluttet WhatsApp Web-nummer medfører et tilbagevendende månedligt vedligeholdelsesgebyr, indtil du afbryder forbindelsen (DELETE /channels/whatsapp-web/connections/{phoneNumber}).

Diriger kanalen til din agent

At forbinde en kanal får den til at fungere; at dirigere den fortæller platformen, hvilken AI-agent der skal besvare helt nye indgående samtaler på den. Indstil kanalens standard-indgangspunkt (Entry Point) for kanalen ved at navngive den agent, du oprettede i trin 2:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'

Gentag kaldet én gang pr. kanal — ét kanal-standardpunkt pr. kanal. For at efterlade en kanal uden en agent til at besvare den, skal du kalde DELETE /entry-points/channel-defaults?channel=whatsapp_web; for at tjekke om Entry Points-stigen er live for kontoen, skal du kalde GET /entry-points/routing-status. Det ældre POST /channels/campaign-kort er kun bevaret til rollback og konsulteres ikke længere til indgående dirigering. Se Kanalguiden for de andre kanaltyper og for WhatsApp Business OAuth-flowet.

Trin 4 — Importér dine kontakter

Når en kanal er aktiv, skal du indlæse de personer, du vil nå. Import-endpointet tager op til 500 poster pr. kald. Hver post kræver et phone_number i internationalt format; alt andet er valgfrit. Poster med ugyldige numre, ikke-understøttede kanaler eller numre, der allerede eksisterer, springes over — og hvert spring rapporteres med indeks og årsag, så du kun kan forsøge at sende de fejlslagne igen.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "defaultChannel": "whatsapp_web"
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/import`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    defaultChannel: "whatsapp_web",
  }),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);

Python

res = requests.post(
    f"{BASE}/contacts/import",
    headers=HEADERS,
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "defaultChannel": "whatsapp_web",
    },
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")

Svaret fortæller dig præcis, hvad der skete:

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}

For oprettelse af enkelte kontakter, listning/opslag, lister, tags og brugerdefinerede felter, se Kontaktguiden.

Trin 5 — Send og læs beskeder

Send en besked

Den simpleste afsendelse er kanal-agnostisk: angiv kontaktens identitet og beskedens indhold, så leverer platformen den på den kanal, kontakten befinder sig på. Du kan målrette efter contact_id eller efter channel plus det matchende identitetsfelt (phone_number for WhatsApp/WhatsApp Web/SMS, instagram_id for Instagram, og så videre).

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "phone_number": "+12025551234",
    "body": "Hi Ann! Thanks for reaching out."
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "whatsapp_web",
    phone_number: "+12025551234",
    body: "Hi Ann! Thanks for reaching out.",
  }),
});
const { message_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/contacts/send",
    headers=HEADERS,
    json={
        "channel": "whatsapp_web",
        "phone_number": "+12025551234",
        "body": "Hi Ann! Thanks for reaching out.",
    },
)
message_id = res.json()["message_id"]

Levering er asynkron — en 201 betyder, at beskeden blev accepteret og sat i kø, ikke nødvendigvis leveret endnu. (Kontakter med ‘forstyr ikke’ eller privat tilstand aktiveret afvises med en 422.)

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp_web"
}

Læs en samtale

For at læse beskeder tilbage, skal du liste dem efter kontakt, nyeste først, med cursor-paginering. Send next_cursor fra ét svar som cursor i det næste for at gå tilbage gennem historikken.

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"

res = requests.get(
    f"{BASE}/contacts/contact123/messages",
    headers=HEADERS,
    params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
    print(msg)
next_cursor = page["next_cursor"]  # pass back as ?cursor= for the next page

Du kan også filtrere efter indholdstype (?filter=text|media|tool_use) eller retning (?direction=inbound|outbound). Beskedguiden dækker medievedhæftninger, markering af beskeder som læst og visninger af beskeder pr. session.

Undlad at polle efter svar. At liste beskeder med et tidsinterval virker, men det spilder forespørgsler og skaber forsinkelse. Brug webhooks til indgående beskeder i stedet — det er Trin 7.

Trin 6 — Læs analyse

Når beskederne flyder, giver analyseoversigten dig aggregerede tællinger over et datointerval: sendt, leveret, læst, besvaret, booket, kontakter oprettet og kreditter brugt/genopfyldt. Du får både totaler for intervallet og en nul-udfyldt serie pr. dag – perfekt til et dashboard-diagram. Du kan valgfrit begrænse det til en enkelt kampagne med campaign_id (eksemplerne nedenfor bruger et pladsholder-kampagne-id, abc123campaign); udelad parameteren for totaler for hele kontoen.

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();

res = requests.get(
    f"{BASE}/analytics/summary",
    headers=HEADERS,
    params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]

Intervallet er som standard de sidste 30 dage og er begrænset til 366. For kredit-for-kredit forbrugsregistreringer og opdelinger af AI-omkostninger, se Analyseguiden.

Trin 7 — Abonner på webhooks for realtidsbegivenheder

Polling er fint til et hurtigt script, men en rigtig integration bør være push-baseret. Webhooks lader platformen kalde din server i det øjeblik, der sker noget — en ny kontakt, et svar, en booket aftale, en afsluttet chat.

Find først de præcise begivenhedsnavne, du kan abonnere på:

curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"

{
  "success": true,
  "events": [
    "Contact Created",
    "Human Alerted",
    "Appointment Booked",
    "Replies",
    "New Message",
    "Chat Concluded",
    "Task Created",
    "Daily Summary Created"
  ]
}

Opret derefter et abonnement, der peger på en HTTPS-URL på din server. Brug de præcise begivenheds-strenge fra kaldet ovenfor.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Lead updates hook"
  }'

JavaScript

const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Lead updates hook",
  }),
});
const { webhook_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Lead updates hook",
    },
)
webhook_id = res.json()["webhook_id"]

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Lead updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

URL’en skal bruge HTTPS og være offentligt tilgængelig. Fra nu af modtager din server en POST for hver begivenhed, du abonnerer på. Du kan sende en testlevering, tjekke et abonnements sundhedstilstand og genaktivere et abonnement, der blev deaktiveret automatisk efter gentagne fejl — se Webhook-guiden og siden Webhooks på integrationsniveau for nyttelast-formater og verificering.

Det hele samlet

Her er hele flowet i korte træk:

Trin	Mål	Nøglekald
1	Autentificer	`GET /health`
2	Opret + finjuster assistenten	`POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours`
3	Forbind en kanal og rut den	`POST /channels/whatsapp-web/connections` → hent QR + status → `PUT /entry-points/channel-defaults`
4	Indlæs kontakter	`POST /contacts/import`
5	Send & læs	`POST /contacts/send`, `GET /contacts/{id}/messages`
6	Mål	`GET /analytics/summary`
7	Reager i realtid	`POST /webhooks`

En minimal wrapper er blot disse syv kald forbundet til din egen brugerflade. Derfra kan du tilføje de ressource-specifikke guides, efterhånden som du får brug for mere:

Kampagner · Kontakter · Ofte stillede spørgsmål · Beskeder · Aftaler
Kanaler · Skabeloner · Analyse · Webhooks · API-nøgler
Ny her? Kom i gang · Autentificering · Fejl & Sidetal

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

Byg en integration fra ende til anden #

Trin 1 — Få en API-nøgle og foretag din første anmodning #

Trin 2 — Opret en AI-agent #

Konfigurer assistenten #

Trin 3 — Tilslut en kanal #

Gennemgang af eksempel: parring af WhatsApp Web via QR-kode #

Diriger kanalen til din agent #

Trin 4 — Importér dine kontakter #

Trin 5 — Send og læs beskeder #

Send en besked #

Læs en samtale #

Trin 6 — Læs analyse #

Trin 7 — Abonner på webhooks for realtidsbegivenheder #

Det hele samlet #

Byg en integration fra ende til anden

Trin 1 — Få en API-nøgle og foretag din første anmodning

Trin 2 — Opret en AI-agent

Konfigurer assistenten

Trin 3 — Tilslut en kanal

Gennemgang af eksempel: parring af WhatsApp Web via QR-kode

Diriger kanalen til din agent

Trin 4 — Importér dine kontakter

Trin 5 — Send og læs beskeder

Send en besked

Læs en samtale

Trin 6 — Læs analyse

Trin 7 — Abonner på webhooks for realtidsbegivenheder

Det hele samlet