Giriş yapınÜcretsiz denemeyi başlatın
easyCoexistence Resmi API'ler

Müşterilerinizin WhatsApp mesajlarını ve sosyal medya yorumlarını webhook ile nasıl alırsınız

Her bağlantı, easyCoexistence'ın Partner API'si üzerinden müşterilerinizin WhatsApp mesajları veya sosyal medya yorumları için kendi webhook'una sahip olur. WhatsApp mesajları Meta'dan doğrudan bu URL'ye gönderilir ve sizin tuttuğunuz bir sır yerine Tech Provider uygulamasının sırrıyla imzalanır; bu nedenle URL yolundaki uzun, rastgele bir sır bu mesajları doğrular. Instagram ve Facebook yorumları ile DM'leri ve TikTok yorumları geldikleri anda iletilir ve her hesap için ayrı bir X-EC-Signature ile imzalanır.

200 characters

Meta'nın, bir numaranın mesajlarını uç noktanıza gönderen alternatif geri çağırma URL'si için izin verdiği azami uzunluk.

7 days

Meta'nın, uç noktanızın kabul etmediği bir WhatsApp webhook'unu ne kadar süreyle ve giderek azalan sıklıkta yeniden denediği; bu da kopyalara yol açabilir.

AS32934

Meta'nın ağı; whois yol sorgularında WhatsApp webhook'larının geldiği adresler listelenir ve Meta bu adresleri periyodik olarak değiştirir.

3 MB

Meta'ya göre bir WhatsApp webhook payload'unun ulaşabileceği en büyük boyut.

5 minutes

İletilen bir olayın imzalı zaman damgasının reddedilmesi gereken yaş; HMAC sabit sürede karşılaştırılır.

Her bağlantı kendi hedefini nasıl alır?

Her kaynak için tek bir çağrıyla. Bir WhatsApp numarası, url ve verify_token içeren PUT /connections/{id}/webhook çağrısıyla ya da bağlantı oturumunda aynı çifti webhook_url ve webhook_verify_token olarak alır; böylece numara ilk dakikadan itibaren size yönlendirilir. Sosyal hesap, bağlandıktan sonra PUT /channels/{id}/webhook ile url alır. Bunlardan birinde url değerinin null olması teslimatı kapatır. İki yol, kimin teslim ettiği ve nasıl doğrulama yapmanız gerektiği bakımından farklılaşır:

WhatsApp numberInstagram, Facebook, TikTok
Set withwebhook_url on the session, or PUT /connections/{id}/webhookPUT /channels/{id}/webhook, after it connects
Delivered byMeta, straight to your URLeasyCoexistence, forwarding each event as it arrives
BodyMeta's webhook, unchangedplatform, account_id, external_id and the network's entry
AuthenticateA long random secret in the URL pathX-EC-Signature, keyed with the account's secret
RetriesMeta's own, for up to 7 daysNone: one attempt
Copy keptNoneNone

Bir numaranın mesajlarını uç noktanıza nasıl yönlendirirsiniz?

URL'nin yolunda uzun, rastgele bir sır bulunan bir HTTPS URL'si ve bir doğrulama token'ı verin: bağlantı oturumunda webhook_verify_token (8 ila 200 karakter) ya da PUT çağrısında verify_token. Meta, URL'yi hemen hub.mode=subscribe, hub.verify_token ve hub.challenge parametreleriyle bir GET isteğiyle kontrol eder; token eşleştiğinde uç noktanız hub.challenge değerini yanıt olarak döndürmelidir. Bu el sıkışma başarısız olursa PUT, Meta'nın kendi mesajıyla birlikte 502 meta_rejected döndürür. Bağlantı oturumunda numara yine de bağlanır ve oturumun last_error alanı URL'nin neden uygulanmadığını açıklar.

Node.js: Meta's handshake and the path secret
import express from "express";
import { timingSafeEqual } from "node:crypto";

const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();

function same(a, b) {
  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
  return x.length === y.length && timingSafeEqual(x, y);
}

// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
    return res.sendStatus(403);
  }
  res.send(req.query["hub.challenge"]);
});

// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  res.sendStatus(200); // answer first: Meta retries for up to 7 days
  enqueue(req.body); // deduplicate on each message id before acting
});

Meta'nın imzasını neden doğrulayamazsınız ve yerine ne kullanılır?

Meta her teslimatı X-Hub-Signature-256 ile imzalar; bu, payload'un alıcı uygulamanın App Secret'ı ile anahtarlanmış bir HMAC-SHA256 değeridir. Müşterilerinizin numaraları için bu uygulama easyCoexistence'ın Tech Provider uygulamasıdır ve sırrı hiçbir zaman paylaşılmaz; bu nedenle başlık sizin tarafınızda doğrulanamaz. Bunun yerine kimlik bilgisi, URL yolundaki uzun, rastgele sırdır: sabit sürede karşılaştırın ve başka her şeyi reddedin. İkinci katman olarak, Meta'nın AS32934 numarasına kayıtlı yolları bir izin listesine ekleyin ve bu listeyi düzenli olarak yenileyin; çünkü Meta IP adreslerini periyodik olarak değiştirir.

Hangi WhatsApp webhook'ları URL'nize ulaşır?

Meta'nın alternatif geri çağırma URL'sinin taşımasına izin verdiği alanlar: müşterilerin gönderdikleri ve sizin gönderdiklerinizin durumu için messages; işletmenin WhatsApp Business uygulamasından gönderdikleri için smb_message_echoes; ve tek seferlik içe aktarmanın geçmişi ile smb_app_state_sync. Meta, şablon webhook'larını ya da account_update gibi hesap webhook'larını hiçbir zaman bir geçersiz kılma URL'sine göndermez; bunlar bunun yerine easyCoexistence'ın geri çağırmasına ulaşır. Bu nedenle şablon incelemesi yoklama ile okunur ve bir kayıp size durum olayı olarak ulaşır.

  • Hedef WhatsApp Business Account'ta ayarlanır, bu yüzden aynı hesaptaki iki numara onu paylaşır: value.metadata.phone_number_id üzerinden yönlendirin.
  • Medya bir ID olarak gelir; dosyayı, kimlik bilgisi çağrısından alınan müşteri token'ı ile Meta'dan çekin.
  • Payload'lar 3 MB'a ulaşabilir; bu değerin altında ayarlanmış herhangi bir gövde boyutu sınırını yükseltin.

İletilen bir sosyal olay nasıl görünür?

Content-Type application/json ve bir X-EC-Signature başlığı içeren bir POST isteği; dört anahtar taşır: platform; account_id, Partner API'nin kullandığı kanal kimliği; external_id, hesabın ağdaki kimliği; ve entry. Instagram ve Facebook için entry, Meta'nın webhook girişidir ve değiştirilmeden iletilir; yorumlar ve bahsetmeler için changes, DM'ler için messaging içerir. TikTok için içinde içeriği ayrıştırılmış comment.update olayı bulunur; comment_id, video_id ve parent_comment_id ise string olarak gelir, böylece 64 bit kimlikler yuvarlanmaz.

  • Instagram hesapları yorumlar, mesajlar ve bahsetmelere abone edilir; Facebook Sayfaları feed, messages ve mention alanlarına abone edilir; TikTok comment.update gönderir.
  • easyCoexistence YouTube ya da LinkedIn'den hiçbir yorum olayı almaz: PUT çağrıları 400 not_supported döndürür ve bu ağların yorumları, kimlik bilgileriyle her ağın API'si üzerinden okunur.
  • İletilmelerde X-EC-Event ya da X-EC-Delivery başlığı bulunmaz; bu yüzden yorum kimliği veya mesaj mid değeri gibi ağın kendi kimlikleriyle tekrarları ayıklayın.
A forwarded Instagram comment
{
  "platform": "instagram",
  "account_id": "<CHANNEL_ID>",
  "external_id": "<INSTAGRAM_ACCOUNT_ID>",
  "entry": {
    "id": "<INSTAGRAM_ACCOUNT_ID>",
    "time": 1793440800,
    "changes": [
      {
        "field": "comments",
        "value": {
          "id": "<COMMENT_ID>",
          "from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
          "text": "<COMMENT_TEXT>",
          "media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
        }
      }
    ]
  }
}

X-EC-Signature'ı adım adım nasıl doğrularsınız?

PUT /channels/{id}/webhook'un döndürdüğü ve yalnızca bir kez gösterilen, o hesaba özgü signing_secret ile. Başlık t=<unix>,v1=<hex> biçimindedir. Ardından her teslimat için:

  • Ham istek gövdesini, herhangi bir JSON ayrıştırmasından önce bayt olarak okuyun.
  • Başlığı virgüllerden bölerek t (saniye cinsinden Unix zamanı) ve v1 (hex özeti) olarak ayırın.
  • t değeriniz saatinizden 5 dakikadan fazla uzaktaysa teslimatı reddedin.
  • t, bir nokta ve ham gövde üzerinden, o hesabın sırrıyla anahtarlanmış HMAC-SHA256 hesaplayın; sonucu hex olarak alın.
  • v1 ile sabit sürede karşılaştırın, ardından 2xx ile yanıt verin ve işi kuyruğa alın.
Node.js: verifying a forwarded event
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database

app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
  );
  if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
    return res.sendStatus(401); // missing or stale timestamp
  }
  let event;
  try {
    event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
  } catch {
    return res.sendStatus(400);
  }
  const secret = secrets.get(event.account_id);
  if (!secret || !sig.v1) return res.sendStatus(401);
  const expected = createHmac("sha256", secret)
    .update(sig.t + ".")
    .update(req.body) // the raw bytes, exactly as they arrived
    .digest("hex");
  if (expected.length !== sig.v1.length ||
      !timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
    return res.sendStatus(401);
  }
  res.sendStatus(204); // one attempt and no retries: acknowledge, then work
  enqueue(event);
});

Hedef ayarlanmadığında ne olur?

Hiçbir şey size ulaşmaz ve sonradan gönderilmek üzere bekletilmez. webhook_url'si olmayan bir numara easyCoexistence'ın geri çağırmasına döner; burada mesajları saklanmadan düşürülür ve sohbet geçmişi içe aktarımı almaz, çünkü bu yalnızca bir hedef var olduğunda istenir. Hedefi olmayan bir sosyal hesap iletilmez: olayları yine easyCoexistence'ın uygulamasına ulaşır, ancak sizin için hiçbiri tutulmaz. Trafiğe ihtiyacınız olmadan önce her hedefi ayarlayın.

Bir bağlantı düşer veya kaldırılırsa hedefe ne olur?

Bir numara hedefini kayıtta tutar. Düşen bir numara yeniden bağlandığında easyCoexistence URL'nizi Meta'ya yeniden ayarlar; askıya alınmış bir numara geri döndüğünde de aynısı olur. Sosyal bir hesabı kaldırmak hedefini ve sırrını temizler; bu nedenle yeniden bağlandıktan sonra PUT /channels/{id}/webhook çağrısını tekrar yapın ve yeni sırrı saklayın. Bu PUT, bir URL ile çağrıldığında her seferinde yeni bir sır üretir ve eski sır hemen imzalamayı bırakır.

Nasıl kurulur

  1. Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
  2. Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
  3. Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
  4. Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.

Yaygın hatalar

  • Müşterilerinizin WhatsApp teslimatlarında X-Hub-Signature-256 değerini kontrol etmek. Meta bunu, hiçbir zaman paylaşılmayan easyCoexistence uygulama sırrıyla hesaplar; bu yüzden kontrol geçemez. URL yolundaki sırla kimlik doğrulaması yapın.
  • X-EC-Signature'ı ayrıştırılmış JSON üzerinden doğrulamak. HMAC, ham gövdeyi bayt bayt kapsar ve yeniden serileştirmek baytları değiştirir; bu nedenle ayrıştırmadan önce doğrulayın.
  • Her kanal için tek bir sır kullanmak. Her sosyal hesap kendi sırrıyla, durum olayları ise başka bir sırla imzalar; bu nedenle sırrı account_id ile arayın.
  • İletilen bir olaya yanıt vermeden önce yavaş iş yapmak. Olay bir kez gönderilir, sizin yanıtınızı 8 saniye bekler ve hiç yeniden denenmez; bu nedenle önce 2xx ile yanıt verin, sonra işleyin.
Bunu EasyCoexistence'la yapmak

easyCoexistence, her müşteri numarasının mesajlarını Meta'dan doğrudan sunucunuza yönlendirir; Instagram ve Facebook yorumları ile DM'lerini ve TikTok yorumlarını ise geldikleri anda, hesap başına imzalı olarak uç noktanıza iletir. Hiçbir kopya tutulmaz ve her bağlantı 7/24 izlenir. Bağlantı başına aylık US$ 9'dan US$ 0.75'e kadar, bağlantı eklendikçe düşen fiyatla; ilk 3 gün ücretsizdir.

Sık sorulan sorular

Müşterilerimin WhatsApp mesajlarında Meta'nın imzasını doğrulayabilir miyim?

Hayır. Meta bunları, hiçbir zaman paylaşılmayan easyCoexistence'ın Tech Provider uygulamasının sırrıyla imzalar. URL yolunuzdaki uzun, rastgele sırla kimlik doğrulaması yapın ve isterseniz isteğe bağlı olarak Meta'nın IP aralıklarını da kullanın.

YouTube ve LinkedIn bağlantıları yorum olaylarını iletir mi?

Hayır. easyCoexistence bunların ikisinden de yorum olayı almaz; bu nedenle PUT /channels/{id}/webhook 400 not_supported döndürür. Yorumlarını, kanalın kimlik bilgileriyle her ağın API'si üzerinden okuyun.

Sunucum kapalıysa iletilen sosyal olaylar yeniden denenir mi?

Hayır. Her biri bir kez gönderilir ve hiçbir kopya tutulmaz. WhatsApp teslimatları farklıdır, çünkü Meta bunları 7 güne kadar kendisi yeniden dener.

Mesajlar easyCoexistence üzerinden geçiyor mu?

WhatsApp'ta geçmez: Meta, bir numaranın mesajlarını sizin ayarladığınız webhook'a doğrudan teslim eder. Sosyal ağlardan gelen yorumlar ve DM'ler ise geldikleri anda, hesap başına imzalı olarak uç noktanıza iletilir; hiçbir kopya tutulmaz.

Okumaya devam edin

İlk kanalınızı iki dakikada bağlayın.

Beklemeniz gereken platform incelemesi yok. WhatsApp, Instagram, TikTok veya başka bir kanalı bağlayın, ardından yapay zekânızdan paylaşım yapmasını, yanıtlamasını ya da rapor vermesini isteyin ve işini izleyin.

  • 3 gün ücretsiz
  • İstediğiniz zaman iptal
  • Yalnızca resmi API'ler
  • 7/24 izleniyor

Doğrulama tarihi