Publicarea aplicațiilor Dify: Web App, embed, Service API și Webhook Trigger în Dify: fluxuri agentice, Knowledge și self-hosting: explicație și exemple

Publish activează ultima versiune a aplicației și o înlocuiește imediat pe cea live. Tab-ul Access Point adună căile de acces: URL-ul aplicației web, Embed Into Site, API-ul, cardul MCP Server și, pentru workflow-urile cu triggere, cardul Trigger. Doar aplicațiile care pornesc din User Input se pot publica ca web app, Service API, server MCP sau unealtă.

Embed. Aplicația web se poate încorpora ca buton de chat plutitor (chat bubble), configurat prin obiectul window.difyChatbotConfig (token, baseUrl, inputs, systemVariables, userVariables, containerProps) și scriptul embed.js, sau ca iframe cu adresa http://gazda-dify/chatbot/TOKEN. Codul exact și tokenul se copiază din Embed Into Site. Valorile din inputs sunt comprimate GZIP și codate base64 în URL.

Service API. Cheia API se creează din aplicație, ține doar de acea aplicație și servește toți utilizatorii finali. Se folosește doar din backend: o cheie din codul de frontend poate fi extrasă. URL-ul de bază este https://api.dify.ai/v1 pe Dify Cloud sau adresa instanței tale (de exemplu http://localhost/v1). Câmpul user este identificatorul tău pentru utilizatorul final; Dify nu îl autentifică, dar după el separă conversațiile, fișierele, oprirea și reluarea rulărilor. response_mode este streaming (SSE, recomandat) sau blocking (implicit dacă lipsește); aplicațiile Agent și Legacy Agent acceptă doar streaming. În stream sosește un ping cam la 10 secunde, apoi evenimente ca message, agent_message, message_end, workflow_finished sau error.

Webhook Trigger este direcția inversă, doar pentru Workflow: Dify generează un URL {TRIGGER_URL}/triggers/webhook/{id}, iar un sistem extern îl apelează la un eveniment. Alegi metoda HTTP și Content-Type, extragi parametri din query, headere și body și poți personaliza răspunsul (cod 200–399, JSON sau text; implicit 200 OK). Payload-ul are cel mult 10 MB (WEBHOOK_REQUEST_BODY_MAX_SIZE). Ca Dify să trimită un webhook spre alt sistem, folosești nodul HTTP Request.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
`POST /chat-messages`	Mesaj către Chatflow, Agent, Chatbot sau Legacy Agent. Obligatorii: `inputs`, `query`, `user`.
`POST /workflows/run`	Rulează versiunea publicată a unui Workflow. Obligatorii: `inputs`, `user`. `POST /workflows/{workflow_id}/run` rulează o versiune anume.
`POST /completion-messages`	Pentru aplicațiile Text Generator.
`inputs`	Valorile câmpurilor din User Input, după nume; numele și tipurile se citesc din `GET /parameters`.
`conversation_id`	Gol sau absent pentru o conversație nouă; răspunsul întoarce ID-ul de trimis la mesajul următor.
`files`	Fișiere atașate: `transfer_method` `remote_url` (cu `url`) sau `local_file` (cu `upload_file_id` de la `POST /files/upload`).
`task_id / workflow_run_id`	`task_id` oprește generarea în curs (`POST /chat-messages/{task_id}/stop`, `POST /workflows/tasks/{task_id}/stop`); `workflow_run_id` identifică rularea salvată și permite reconectarea cu `GET /workflow/{workflow_run_id}/events`.
`Erori`	Corp JSON cu `code`, `message`, `status`. 429 `too_many_requests` se reîncearcă cu pauză; `provider_not_initialize` sau `provider_quota_exceeded` cer corectarea configurației modelului.
`Embed Into Site`	Codul pentru chat bubble sau iframe, cu tokenul aplicației web.
`Webhook Trigger`	URL generat de Dify pentru porniri din exterior; folosește URL-ul de test până la publicare.

Exemple practice și scenarii reale

Exemplul 1: Un mesaj către un Chatflow, în modul blocking

Răspunsul conține answer, conversation_id, message_id, task_id și metadata cu usage (tokeni, cost, latență) și, dacă aplicația folosește Knowledge, retriever_resources (bază, document, scor, fragment).

curl -X POST "https://dify.example.com/v1/chat-messages" \
  -H "Authorization: Bearer $DIFY_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "Cum schimb parola contului de client?",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "client-5544"
  }'

Exemplul 2: Un Workflow în modul streaming, din Python

Liniile care nu încep cu data: (separatori și ping) se ignoră. Timeout-ul de citire trebuie să fie mai mare decât intervalul de 10 secunde al ping-ului.

import json
import os

import requests

url = "https://dify.example.com/v1/workflows/run"
headers = {"Authorization": f"Bearer {os.environ['DIFY_APP_KEY']}"}
body = {
    "inputs": {"tichet": "Nu pot descărca factura."},
    "response_mode": "streaming",
    "user": "client-5544",
}

with requests.post(url, headers=headers, json=body, stream=True, timeout=(10, 60)) as r:
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue
        ev = json.loads(line[len("data: "):])
        if ev["event"] == "workflow_finished":
            print(ev["data"]["status"], ev["data"]["outputs"])
        elif ev["event"] == "error":
            print(ev["code"], ev["message"])

Exemplul 3: Chat bubble pe un site

Configurația se încarcă înaintea scriptului embed.js; scriptul îl copiezi din Embed Into Site.

<script>
  window.difyChatbotConfig = {
    token: 'TOKEN_DIN_EMBED_INTO_SITE',
    baseUrl: 'https://dify.example.com',
    inputs: { departament: 'Suport' },
    systemVariables: { user_id: 'USER_123' },
  }
</script>
<!-- urmează scriptul embed.js din Embed Into Site -->

Exemplul 4: Testarea unui Webhook Trigger

În trigger alegi metoda POST, Content-Type application/json și parametrii de body orderId (String) și isPriority (Boolean). Apeși Run this step ca trigger-ul să asculte, apoi trimiți cererea la URL-ul de test.

curl -X POST "$URL_WEBHOOK_DE_TEST" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "A-1001", "isPriority": true}'

Greșeli frecvente și capcane

Pui cheia API a aplicației în JavaScript-ul din browser. Apelează Service API doar din backend; pentru site-uri publice folosește embed-ul aplicației web.
Trimiți alt user la încărcarea fișierului, la mesaj, la oprire sau la reconectare. Fiecare pas verifică user; un fișier încărcat sub alt user nu poate fi folosit. Conversațiile din API și cele din aplicația web nu se văd între ele.
Folosești blocking pentru generări lungi. Proxy-urile pot închide conexiunea (pe Dify Cloud, timeout-ul Cloudflare este de 100 s); folosește streaming și salvează workflow_run_id pentru reconectare.
Configurezi un Webhook Trigger cu TRIGGER_URL lăsat pe http://localhost. Sistemele externe nu pot apela adresa; setează un domeniu sau un IP public.

`Publicarea aplicațiilor Dify: Web App, embed, Service API și Webhook Trigger` în Dify: fluxuri agentice, Knowledge și self-hosting