API kanalı

Kendi sohbet uygulamanızı kanal olarak bağlayın: müşteri mesajını imzalı istekle gönderin, temsilci yanıtını webhook ile alın.

Kendi sohbet uygulamanızı ya da sisteminizi bir kanal olarak bağlamak için API kanalı kullanılır; web sitesinde buna gerek yoktur, widget zaten kanaldır. Kanal Kanallar → Kanal ekle → API ile kurulur; size gelen adres (/v1/webhooks/channels/api/{instance}), bir imza anahtarı ve temsilci yanıtlarının gönderileceği adresi girmeniz için bir alan verilir.

Müşteri mesajı → ClickFix: POST /v1/webhooks/channels/api/{instance} gövdesi { id, sender_id, sender_name?, text, thread_id?, reply_to?, at? }. İstek API anahtarıyla değil kanalın imza anahtarıyla doğrulanır: X-ClickFix-Timestamp (Unix saniye) ve X-ClickFix-Signature: sha256= + hex(HMAC-SHA256(imza_anahtarı, timestamp + "." + ham_gövde)). sender_id müşterinin sizin sisteminizdeki kimliğidir; aynı id bir kez kaydedilir.
Temsilci yanıtı → siz: ClickFix, kanalda tanımladığınız adrese apiChannelReply gövdesiyle POST atar; aynı imza başlıkları ve mesaj UUID'sini taşıyan Idempotency-Key ile. Mesajı kaydettikten sonra 2xx dönün; 408 ve 429 dışındaki 4xx kalıcı hata sayılır. Doğrulama webhook imzasıyla aynıdır (v1= yerine sha256=).

// Adım 6: web'de API kanalı gerekmez; widget zaten kanaldır. Kendi arayüzünüz
// varsa @getclickfix/react-widget'ın arayüzsüz istemcisini kullanın.
// @ts-check
ClickFix("on", "message", (m) => {
  // Temsilci veya AI yanıtı: kendi bildirim sisteminize aktarabilirsiniz
  console.log(m.conversation_uuid, m.sender_type, m.text);
});

// Adım 6: API kanalı. Kendi uygulamanızdaki müşteri mesajını ClickFix'e
// gönderin; imza API anahtarıyla değil kanalın imza anahtarıyla atılır.
import { createHmac } from "node:crypto";

const base = process.env.CLICKFIX_BASE_URL!;
const instance = process.env.CLICKFIX_CHANNEL_INSTANCE!; // Kanallar > API kanalı
const secret = process.env.CLICKFIX_CHANNEL_SECRET!;

const body = JSON.stringify({
  id: `msg-${Date.now()}`, // kanal içinde tekil; aynı id bir kez kaydedilir
  sender_id: "1001", // müşterinin sizin sisteminizdeki kimliği
  sender_name: "Ayşe Yılmaz",
  text: "Siparişim ne zaman gelir?",
});
const timestamp = String(Math.floor(Date.now() / 1000));
const signature =
  "sha256=" +
  createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(body)
    .digest("hex");

const res = await fetch(`${base}/v1/webhooks/channels/api/${instance}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-ClickFix-Timestamp": timestamp,
    "X-ClickFix-Signature": signature,
  },
  body,
});
if (!res.ok) throw new Error(`ClickFix ${res.status}`);
console.log(JSON.stringify(await res.json()));

package main

import (
	"bytes"
	"context"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"strconv"
	"time"
)

// Adım 6: API kanalına müşteri mesajı gönder; imza kanalın imza anahtarıyla.
func apiChannel(ctx context.Context) error {
	base, instance, secret := os.Getenv("CLICKFIX_BASE_URL"), os.Getenv("CLICKFIX_CHANNEL_INSTANCE"), os.Getenv("CLICKFIX_CHANNEL_SECRET")
	body, _ := json.Marshal(map[string]string{
		"id":          fmt.Sprintf("msg-%d", time.Now().UnixNano()), // kanal içinde tekil
		"sender_id":   "1001",                                       // müşterinin sizin sisteminizdeki kimliği
		"sender_name": "Ayşe Yılmaz",
		"text":        "Siparişim ne zaman gelir?",
	})
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(body)
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, base+"/v1/webhooks/channels/api/"+instance, bytes.NewReader(body))
	if err != nil {
		return err
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-ClickFix-Timestamp", timestamp)
	req.Header.Set("X-ClickFix-Signature", "sha256="+hex.EncodeToString(mac.Sum(nil)))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return fmt.Errorf("clickfix: HTTP %d", res.StatusCode)
	}
	return json.NewEncoder(os.Stdout).Encode(map[string]int{"status": res.StatusCode})
}

<?php
// Adım 6: API kanalı. Kendi uygulamanızdaki müşteri mesajını ClickFix'e
// gönderin; imza API anahtarıyla değil kanalın imza anahtarıyla atılır.
require __DIR__.'/vendor/autoload.php';

use ClickFix\ApiChannel;

$channel = new ApiChannel(
    getenv('CLICKFIX_BASE_URL'),
    getenv('CLICKFIX_CHANNEL_INSTANCE'), // Kanallar > API kanalı
    getenv('CLICKFIX_CHANNEL_SECRET'),
);

// X-ClickFix-Timestamp ve X-ClickFix-Signature başlıklarını SDK ekler.
$received = $channel->send([
    'id' => 'msg-'.(int) (microtime(true) * 1000), // kanal içinde tekil; aynı id bir kez kaydedilir
    'sender_id' => '1001', // müşterinin sizin sisteminizdeki kimliği
    'sender_name' => 'Ayşe Yılmaz',
    'text' => 'Siparişim ne zaman gelir?',
]);

echo json_encode($received), PHP_EOL;

# Adım 6: API kanalına müşteri mesajı; imza kanalın imza anahtarıyla (API anahtarı değil).
BODY='{"id":"msg-'$(date +%s)'","sender_id":"1001","sender_name":"Ayşe Yılmaz","text":"Siparişim ne zaman gelir?"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$CLICKFIX_CHANNEL_SECRET" | sed 's/^.* //')
curl -sS --fail-with-body -X POST "$CLICKFIX_BASE_URL/v1/webhooks/channels/api/$CLICKFIX_CHANNEL_INSTANCE" \
  -H "Content-Type: application/json" \
  -H "X-ClickFix-Timestamp: $TS" \
  -H "X-ClickFix-Signature: sha256=$SIG" \
  -d "$BODY"