Terug naar dashboard

Documentatie

Leer hoe u Asyntai kunt gebruiken

API-referentie

Bouw aangepaste integraties met de Asyntai REST API

API-sleutel ophalen

Betaald abonnement vereist: API-toegang is beschikbaar op Starter, Standard en Pro plannen. Prijzen bekijken

Overzicht

The Asyntai API allows you to integrate AI-powered customer support into any application. Send messages and receive intelligent responses grounded in your website content and knowledge base.

Authenticatie

Alle API-verzoeken vereisen authenticatie met uw API-sleutel. U kunt uw API-sleutel ophalen op de pagina API-instellingen.

Voeg uw API-sleutel toe aan verzoeken met een van deze methoden:

  • Authorization-header (aanbevolen): Authorization: Bearer YOUR_API_KEY
  • X-API-Key-header: X-API-Key: YOUR_API_KEY

Houd uw API-sleutel geheim. Iedereen met uw sleutel heeft toegang tot uw account via de API. Maak deze nooit zichtbaar in client-side code.

Basis-URL

https://asyntai.com/api/v1/

Endpoints

POST /chat/

Verstuur een bericht en ontvang een AI-gegenereerd antwoord.

Verzoekinhoud

{
  "message": "What are your business hours?",
  "session_id": "user_123",      // optional
  "website_id": 1                 // optional
}
Parameter Type Vereist Beschrijving
message string Ja Het bericht van de gebruiker om naar de AI te sturen
session_id string Nee Unieke identificatie voor het gesprek. Gebruik dezelfde session_id om de gespreksgeschiedenis te behouden.
website_id integer Nee Specifiek website-ID. Indien niet opgegeven, wordt uw primaire website gebruikt.

Antwoord

{
  "success": true,
  "response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
  "session_id": "user_123"
}

Voorbeeld (cURL)

curl -X POST https://asyntai.com/api/v1/chat/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your business hours?", "session_id": "user_123"}'

Voorbeeld (Python)

import requests

response = requests.post(
    "https://asyntai.com/api/v1/chat/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "message": "What are your business hours?",
        "session_id": "user_123"
    }
)

data = response.json()
print(data["response"])

Voorbeeld (JavaScript)

const response = await fetch("https://asyntai.com/api/v1/chat/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    message: "What are your business hours?",
    session_id: "user_123"
  })
});

const data = await response.json();
console.log(data.response);

GET /websites/

Toon alle websites die aan uw account zijn gekoppeld.

Antwoord

{
  "success": true,
  "websites": [
    {
      "id": 1,
      "name": "My Website",
      "domain": "example.com",
      "is_primary": true
    }
  ]
}

Voorbeeld (cURL)

curl https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /websites/

Create a new AI agent. This does the same thing as adding a website in your dashboard: it makes the agent, reads your site, and writes the first draft of the AI instructions.

Use this to set up customers from your own software. You get back the widget ID and the code to put on the website.

Verzoekinhoud

Veld Type Beschrijving
domain string Required. The website address, for example example.com
name string Optional. A display name for the agent. Useful when one website has several agents.
crawl boolean Optional, true by default. Set it to false to create the agent without reading the website. Nothing is crawled and no instructions are written.
force boolean Optional, false by default. Set it to true to add a website you already have. The copy is stored with a number after it.

Antwoord

{
  "success": true,
  "website": {
    "id": 42,
    "domain": "example.com",
    "name": "Support agent",
    "widget_id": "asyntai_ab12cd34ef56",
    "is_primary": true,
    "crawl_started": true,
    "instructions_status": "generating",
    "job_id": "8f2c1e90-..."
  },
  "embed_code": "<script>...</script>"
}

Voorbeeld (cURL)

curl -X POST https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "name": "Support agent"}'

Reading a website takes a few minutes, so this call answers straight away. Check when the agent is ready with the next endpoint.

Errors

Code Meaning
403 You have reached the number of websites your plan allows. The answer tells you the limit.
409 Your account already has this website. Send force as true to add it again.

GET /websites/{id}/

Get one website and see whether it is ready. Use this after you create an agent, to wait until the website has been read and the AI instructions are written.

Antwoord

{
  "success": true,
  "website": {
    "id": 42,
    "domain": "example.com",
    "name": "Support agent",
    "widget_id": "asyntai_ab12cd34ef56",
    "is_primary": true,
    "created_at": "2026-08-11T09:12:00+00:00",
    "ready": true,
    "instructions": {
      "status": "completed",
      "has_instructions": true,
      "characters": 3421
    },
    "crawl": {
      "job_id": "8f2c1e90-...",
      "status": "completed",
      "pages_crawled": 47,
      "pages_found": 50,
      "max_pages": 50,
      "completed_at": "2026-08-11T09:15:31+00:00",
      "error": ""
    },
    "knowledge_items": 47
  },
  "embed_code": "<script>...</script>"
}

The ready field is true when nothing is still running. A crawl that failed also counts as ready, because it has finished. Look at the crawl status to see what happened.

Voorbeeld (cURL)

curl https://asyntai.com/api/v1/websites/42/ \
  -H "Authorization: Bearer YOUR_API_KEY"

GET PATCH /websites/{id}/settings/

Read or change the chat widget settings for one website. These are the same settings you see on the Customize page: colours, the name of the assistant, the first message, lead capture, and everything else.

Reading the settings

A GET request returns every setting with its current value, plus a locked list. Locked shows the settings your plan cannot change, and which plans they need.

{
  "success": true,
  "settings": {
    "ai_support_name": "AI Assistant",
    "widget_color": "#6366f1",
    "initial_message": "Hi, how can I help you?",
    "hide_branding": false,
    "...": "..."
  },
  "locked": {
    "hide_branding": ["pro", "enterprise"],
    "widget_style": ["pro", "enterprise"]
  }
}

Changing the settings

A PATCH request changes only the settings you send. Everything you leave out stays as it is.

curl -X PATCH https://asyntai.com/api/v1/websites/42/settings/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ai_support_name": "Ava", "widget_color": "#0f172a", "use_emoji": true}'
{
  "success": true,
  "updated": ["ai_support_name", "use_emoji", "widget_color"],
  "settings": { "...": "..." },
  "locked": { "...": "..." }
}

Plans

Each setting needs its own plan, the same as in the dashboard. For example, hiding the Asyntai branding needs the Pro plan, and voice input needs Standard.

Plan needed Instellingen Examples
Any paid plan 25 widget_color, ai_support_name, initial_message
Starter en hoger 22 profile_picture, conversation_starters_enabled
Standard en hoger 25 speech_to_text_enabled, image_vision_enabled, escalation_enabled
Pro 6 hide_branding, widget_style

If you send a setting your plan does not allow, the whole request is refused with code 403 and nothing is saved. The same happens if any value is wrong, for example a colour that is not a hex code. Your settings never end up half changed.

GET PUT /websites/{id}/instructions/

Read or replace the AI instructions for one website. These are the rules that tell the assistant who it is, what it may say, and what it must not say. They are the same instructions you edit in the dashboard.

Reading

{
  "success": true,
  "instructions": "You are the support agent for Acme Tools...",
  "characters": 1979,
  "version": 7,
  "mode": "instructions",
  "ask_questions": true,
  "generation_status": "completed",
  "being_edited_by": null
}

Replacing

A PUT request replaces the whole text, the same as saving in the dashboard. There is no append mode. To add a paragraph, read the instructions, add your text, then write it back.

curl -X PUT https://asyntai.com/api/v1/websites/42/instructions/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions": "You are the support agent for Acme Tools...", "version": 7}'

Verzoekinhoud

Veld Type Beschrijving
instructions string Required. The complete new text. It replaces everything that was there.
version number Optional but recommended. The version you read. If somebody changed the instructions since then, your write is refused instead of overwriting their work.
mode string Optional. Either instructions or general.
ask_questions boolean Optional. Whether the assistant asks a follow-up question at the end of its answers.
force boolean Optional, false by default. Needed only when your new text is less than half the length of the current text.

How your instructions are protected

Instructions can take hours to write, so a write can be refused to protect them:

Code Meaning
400 Your new text is less than half the length of the current text. This catches a script that sends empty or cut-off text over instructions somebody spent hours on. Send force as true if you meant it.
409 The instructions changed after you read them. Read them again, apply your change, then write.
423 Somebody is editing the instructions in the dashboard right now. The answer tells you who. Try again in a couple of minutes.

Every change also saves a copy of the previous text, so an earlier version can always be restored from the dashboard.

GET /conversations/

Haal de gespreksgeschiedenis op voor een specifieke sessie.

Queryparameters

Parameter Type Vereist Beschrijving
session_id string Ja Het sessie-ID waarvoor de geschiedenis moet worden opgehaald
limit integer Nee Maximaal aantal berichten om te retourneren (standaard: 50, max: 100)

Antwoord

{
  "success": true,
  "session_id": "user_123",
  "messages": [
    {
      "role": "user",
      "content": "What are your business hours?",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
      "timestamp": "2024-01-15T10:30:01Z",
      "sender_type": "ai",
      "agent_name": null,
      "response_time_ms": 1840.5
    }
  ]
}

Een vraag en het antwoord staan in één record, dus beide dragen dezelfde timestamp. Trek ze niet van elkaar af om de antwoordsnelheid te meten, want de uitkomst is altijd nul. Gebruik response_time_ms, de werkelijke tijd die het antwoord kostte, in milliseconden.

sender_type is ai wanneer de chatbot antwoordde en human wanneer een van uw agents het gesprek overnam. agent_name bevat de weergavenaam van die agent.

Voorbeeld (cURL)

curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /sessions/

Toon uw recente chatsessies. Gebruik dit om sessie-ID's te ontdekken, die u vervolgens kunt doorgeven aan /conversations/ om de volledige berichtgeschiedenis op te halen.

Queryparameters

Parameter Type Vereist Beschrijving
limit integer Nee Aantal recente sessies om te retourneren (standaard: 20, max: 100)
website_id string Nee Filter sessies op een specifiek website-ID
source string Nee Filteren op sessiebron: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier

Antwoord

{
  "success": true,
  "sessions": [
    {
      "session_id": "session_abc123def",
      "source": "widget",
      "message_count": 5,
      "first_message": "What are your business hours?",
      "first_message_at": "2024-01-15T10:30:00Z",
      "last_message_at": "2024-01-15T10:35:00Z",
      "first_response_time_ms": 1840.5,
      "first_human_response_at": null,
      "started_at": "2024-01-15T10:29:58Z",
      "ended_at": "2024-01-15T10:41:12Z",
      "taken_over_at": null,
      "website_domain": "example.com"
    }
  ]
}

Tijdstempelvelden voor rapportage

Veld Beschrijving
started_at Wanneer de bezoeker de chat opende. Alleen beschikbaar voor widgetsessies, omdat sessies die via de API worden aangemaakt nooit een widget openen.
first_message_at Wanneer het eerste bericht van het gesprek is opgeslagen.
first_response_time_ms Hoe lang het eerste antwoord duurde, in milliseconden. Gebruik dit voor de eerste responstijd.
first_human_response_at Wanneer een van uw agents het eerste antwoord stuurde. De waarde is null wanneer de chatbot het hele gesprek afhandelde.
taken_over_at Wanneer een agent de chat overnam van de chatbot.
last_message_at Wanneer het laatste bericht van het gesprek is opgeslagen.
ended_at Wanneer de bezoeker de chat verliet. Een chat heeft geen opgeloste of gesloten status, omdat een bezoeker altijd kan terugkomen en nog een vraag kan stellen.

Alle tijdstempels zijn in UTC en gebruiken de ISO 8601-notatie. U kunt de tijdzone niet wijzigen. Reken de waarden om in uw eigen rapportagetool.

Voorbeeld (cURL)

curl "https://asyntai.com/api/v1/sessions/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /leads/

Verzamelde leads ophalen — e-mailadressen en telefoonnummers die door bezoekers zijn ingediend tijdens chatgesprekken.

Queryparameters

Parameter Type Vereist Beschrijving
limit integer Nee Aantal leads om terug te geven (standaard: 50, max: 100)
website_id string Nee Filter leads op een specifiek website-ID

Antwoord

{
  "success": true,
  "leads": [
    {
      "session_id": "session_abc123def",
      "email": "[email protected]",
      "phone": "+1234567890",
      "page_url": "https://example.com/pricing",
      "started_at": "2024-01-15T10:30:00Z"
    }
  ]
}
Veld Type Beschrijving
session_id string De chatsessie-ID. Geef dit door aan /conversations/ om de volledige chatgeschiedenis te zien.
email string of null E-mailadres verstrekt door de bezoeker, of null indien niet verzameld
phone string of null Telefoonnummer verstrekt door de bezoeker, of null indien niet verzameld
page_url string of null De pagina-URL waar de bezoeker aan het chatten was
started_at string ISO 8601 tijdstempel van wanneer de chatsessie begon

Voorbeeld (cURL)

curl "https://asyntai.com/api/v1/leads/?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Voorbeeld (Python)

import requests

response = requests.get(
    "https://asyntai.com/api/v1/leads/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"limit": 20}
)

leads = response.json()["leads"]
for lead in leads:
    print(f"{lead['email'] or ''} | {lead['phone'] or ''}")

GET /account/

Haal uw accountinformatie en gebruiksstatistieken op.

Antwoord

{
  "success": true,
  "account": {
    "email": "[email protected]",
    "plan": "starter",
    "messages_used": 150,
    "messages_limit": 2500
  }
}

Voorbeeld (cURL)

curl https://asyntai.com/api/v1/account/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Meerdere websites? Kennisbank-endpoints gebruiken standaard uw primaire website. Als u meerdere websites heeft, geef dan website_id om een specifieke te targeten. U kunt uw website-ID's vinden met GET /websites/.

Dagelijkse uploadlimieten: Kennisbank-uploads (tekst, URL, spreadsheet) zijn onderworpen aan een dagelijkse tekenlimiet op basis van uw abonnement. Dit geldt voor de totale inhoud die per dag via alle kennisbank-endpoints wordt geüpload.

Abonnement Tekens/dag
Starter300.000
Standard1.500.000
Pro6.000.000

GET /knowledge/

Toon uw kennisbankitems. Dit zijn de inhoudsbronnen die uw AI-chatbot gebruikt om vragen te beantwoorden.

Queryparameters

Parameter Type Vereist Beschrijving
limit integer Nee Aantal items om te retourneren (standaard: 50, max: 100)
website_id string Nee Filter op website-ID (standaard uw primaire website)

Antwoord

{
  "success": true,
  "entries": [
    {
      "id": "abc-123-def",
      "type": "text",
      "title": "Business Hours",
      "description": "Manual text content (150 words)",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "ghi-456-jkl",
      "type": "url",
      "title": "About Us - Example",
      "description": "Content from https://example.com/about",
      "created_at": "2024-01-14T09:00:00Z"
    }
  ]
}

Voorbeeld (cURL)

curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /knowledge/text/

Voeg aangepaste tekstinhoud toe aan uw kennisbank. De AI gebruikt dit om vragen van bezoekers te beantwoorden.

Verzoekinhoud

{
  "title": "Return Policy",
  "content": "We offer a 30-day return policy on all items. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
  "website_id": "123"
}
Parameter Type Vereist Beschrijving
title string Ja Een titel voor dit kennisbankitem
content string Ja De tekstinhoud (minimaal 10 tekens)
website_id string Nee Doelwebsite (standaard uw primaire website)

Antwoord

{
  "success": true,
  "id": "abc-123-def",
  "title": "Return Policy",
  "chunks_created": 1
}

Voorbeeld (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/text/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Return Policy", "content": "We offer a 30-day return policy..."}'

POST /knowledge/url/

Voeg een webpagina toe aan uw kennisbank. De inhoud wordt automatisch opgehaald en geëxtraheerd.

Verzoekinhoud

{
  "url": "https://example.com/faq",
  "website_id": "123"
}
Parameter Type Vereist Beschrijving
url string Ja De URL waarvan de inhoud moet worden opgehaald
website_id string Nee Doelwebsite (standaard uw primaire website)

Antwoord

{
  "success": true,
  "id": "abc-123-def",
  "title": "FAQ - Example",
  "url": "https://example.com/faq",
  "chunks_created": 5
}

Voorbeeld (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/url/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/faq"}'

POST /knowledge/spreadsheet/

Upload een CSV- of Excel-spreadsheet (.xlsx) naar uw kennisbank. Elke rij wordt een apart kennisbankitem, ideaal voor productcatalogi, FAQ-lijsten, prijstabellen en adreslijsten.

Verzoek

Verzend als multipart/form-data (bestandsupload), niet als JSON.

Parameter Type Vereist Beschrijving
file bestand Ja Een .csv- of .xlsx-bestand. De eerste rij moet kolomkoppen bevatten. Maximaal aantal rijen per upload: Starter 500, Standard 2.000, Pro 10.000. Overtollige rijen worden afgekapt.
website_id string Nee Doelwebsite (standaard uw primaire website)

Antwoord

{
  "success": true,
  "id": "abc-123-def",
  "title": "products.csv",
  "rows_processed": 15,
  "chunks_created": 15
}

Voorbeeld (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

GET /knowledge/{id}/

Lees één item uit de kennisbank, inclusief de tekst die ervoor is opgeslagen. De waarde id komt uit het antwoord van GET /knowledge/.

Inhoud wordt geretourneerd voor de items die u zelf hebt toegevoegd: tekst, bestanden, spreadsheets, losse URL's en video's. Een website-crawl staat wel in de lijst, maar de pagina's ervan worden niet geretourneerd, omdat de bron uw eigen openbare website is. In dat geval is content gelijk aan null en legt het veld reason uit waarom.

Antwoord

{
  "success": true,
  "id": "abc-123-def",
  "type": "text",
  "title": "Business Hours",
  "description": "Manual text content (150 words)",
  "created_at": "2024-01-15T10:30:00Z",
  "chunks_count": 3,
  "content": "We are open Monday to Friday, 9am to 5pm...",
  "content_available": true,
  "char_count": 43
}

Voorbeeld (cURL)

curl "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE /knowledge/{id}/

Verwijder een kennisbankitem. Het id is te vinden in het antwoord van GET /knowledge/.

Antwoord

{
  "success": true,
  "message": "Knowledge base entry deleted"
}

Voorbeeld (cURL)

curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Tip: U kunt webhooks ook beheren via de API-instellingen pagina zonder code te schrijven.

GET /webhooks/

Toon uw geregistreerde webhooks.

Antwoord

{
  "success": true,
  "webhooks": [
    {
      "id": "abc-123-def",
      "url": "https://example.com/webhook",
      "events": ["message.received", "escalation.requested"],
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Voorbeeld (cURL)

curl "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /webhooks/

Registreer een nieuwe webhook om realtime evenementmeldingen te ontvangen.

Beschikbare gebeurtenissen

Gebeurtenis Beschrijving
message.received Een bezoeker heeft een bericht gestuurd en een antwoord ontvangen
conversation.started Er is een nieuwe chatsessie gestart
escalation.requested De AI heeft een escalatie naar een menselijke medewerker geactiveerd
takeover.started Een menselijke medewerker heeft een chatsessie overgenomen

Verzoekinhoud

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "escalation.requested"],
  "website_id": "123"
}
Parameter Type Vereist Beschrijving
url string Ja De HTTPS-URL om webhook POST-verzoeken te ontvangen
events array Ja Lijst met gebeurtenissen om u op te abonneren (zie tabel hierboven)
website_id string Nee Doelwebsite (standaard uw primaire website)

Antwoord

{
  "success": true,
  "webhook": {
    "id": "abc-123-def",
    "url": "https://example.com/webhook",
    "events": ["message.received", "escalation.requested"],
    "secret": "whsec_abc123...",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Webhooks verifiëren: Elke webhook bevat een secret (alleen getoond bij aanmaak). Elke POST naar uw URL bevat een X-Webhook-Signature header \u2014 een HMAC-SHA256 van de verzoekbody ondertekend met uw geheim.

Voorbeeld (cURL)

curl -X POST "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhook", "events": ["message.received"]}'

DELETE /webhooks/{id}/

Verwijder een webhook. Het id is te vinden in het antwoord van GET /webhooks/.

Antwoord

{
  "success": true,
  "message": "Webhook deleted"
}

Voorbeeld (cURL)

curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Foutmeldingen

Alle foutmeldingen volgen dit formaat:

{
  "success": false,
  "error": "Error message describing what went wrong"
}
Statuscode Beschrijving
400 Ongeldig verzoek - Ongeldige parameters of ontbrekende verplichte velden
401 Niet geautoriseerd - Ongeldige of ontbrekende API-sleutel
429 Te veel verzoeken - Berichtlimiet bereikt voor uw abonnement
503 Service niet beschikbaar - AI-service tijdelijk niet beschikbaar

Snelheidslimieten

API-gebruik is beperkt op basis van uw abonnement:

  • Free: 100 berichten/maand
  • Starter ($39/mnd): 2.500 berichten/maand
  • Standard ($139/mnd): 15.000 berichten/maand
  • Pro ($449/mnd): 50.000 berichten/maand

Hulp nodig?

Als u vragen heeft of problemen ondervindt, neem dan contact met ons op via [email protected].