API di Tempat Platform WhatsApp Business

Notifikasi Pesan yang Diterima

Saat Anda menerima pesan masuk, notifikasi dikirimkan ke URL Webhook yang Anda atur di pengaturan aplikasi. Dokumen ini membahas pesan masuk yang dapat Anda terima dan menyediakan beberapa contoh.

Objek Notifikasi

Notifikasi pesan diterima dapat berisi objek berikut:

Saat Anda menerima pesan dengan media, klien API WhatsApp Business akan mengunduh media tersebut. Notifikasi dikirim ke Webhooks Anda begitu media diunduh. Notifikasi ini berisi informasi yang mengidentifikasi objek media dan memungkinkan Anda menemukan dan mengambil objek tersebut. Gunakan endpoint Media dengan id media untuk mengambil media.

Contoh Pesan Diterima

Pesan Teks

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
      },
    "wa_id": "16315551234"
  }],
  "messages":[{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1518694235",
    "text": {
      "body": "Hello this is an answer"
    },
    "type": "text"
  }]
}

Pesan Lokasi Statis

{
  "contacts": [{
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
 "messages":[{
   "from":"16315551234",
   "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
   "location":{
      "address":"Main Street Beach, Santa Cruz, CA",
      "latitude":38.9806263495,
      "longitude":-131.9428612257,
      "name":"Main Street Beach",
      "url":"https://foursquare.com/v/4d7031d35b5df7744"},
   "timestamp":"1521497875",
   "type":"location"
 }]
}

Pesan Kontak

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "contacts": [{
      "addresses": [{
        "city": "Menlo Park",
        "country": "United States",
        "country_code": "us",
        "state": "CA",
        "street": "1 Hacker Way",
        "type": "WORK",
        "zip": "94025"
      }],
      "birthday": "2012-08-18",
      "emails": [{
        "email": "kfish@fb.com",
        "type": "WORK"
      }],
      "ims": [{
        "service": "AIM",
        "user_id": "kfish"
      }],
      "name": {
        "first_name": "Kerry",
        "formatted_name": "Kerry Fisher",
        "last_name": "Fisher"
      },
      "org": {
        "company": "Meta",
 	"department": "WhatsApp"
      },
      "phones": [{
        "phone": "+1 (940) 555-1234",
        "type": "CELL"
        },
        {
          "phone": "+1 (650) 555-1234",
          "type": "WORK",
          "wa_id": "16505551234"
      }],
      "urls": [{
        "url": "https://www.facebook.com",
        "type": "WORK"
      }]
    }],
    "from": "16505551234",
    "id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR",
    "timestamp": "1537248012",
    "type": "contacts"
  }]
}

Pengaturan contact_image akan kosong jika klien konsumen menggunakan iPhone.

Pesan Media

Pesan berisi gambar:

{
	"messages": [{
		"from": "16315551234",
		"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
		"image": {
			"file": "/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683",
			"id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
			"mime_type": "image/jpeg",
			"sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
			"caption": "Check out my new phone!",
			"status": "downloaded"
		},
		"timestamp": "1521497954",
		"type": "image"
	}]
}

Mulai versi 2.49.1, Webhooks pesan media berisi status dan ID dari media yang diterima.

Status unduh

StatusDeskripsi

downloaded

Media berhasil diunduh

retriable

Media belum diunduh, namun unduhan dapat dicoba lagi menggunakan endpoint coba lagi

undownloaded

Media mungkin belum diunduh

Kolom caption opsional untuk pesan media. Ini hanya disertakan jika pengguna telah mengatur keterangan.

Pesan berisi dokumen:

{
  "messages": [{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1522189546",
    "type": "document",
    "document": {
      "caption": "80skaraokesonglistartist",
			"file": "/usr/local/wamedia/shared/fc233119-733f-49c-bcbd-b2f68f798e33",
			"id": "fc233119-733f-49c-bcbd-b2f68f798e33",
			"mime_type": "application/pdf",
			"sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e",
			"status": "downloaded"
		}
	}]
}

Pesan suara:

{
    "messages":[{
        "from": "16315551234",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
        "timestamp": "1521827831",
        "type": "voice",
        "voice": {
            "file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2",
            "id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
            "mime_type": "audio/ogg; codecs=opus",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710",
            "status": "downloaded"
        }
  }]
}

Pesan berisi stiker:

{
  "messages":[{
        "from": "16315551234",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
        "timestamp": "1521827831",
        "type": "sticker",
        "sticker": {
            "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
            "metadata": {
                "sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
                "sticker-pack-name" : "Happy New Year",
                "sticker-pack-publisher" : "Kerry Fisher",
                "emojis": ["🐥", "😃"],
                "ios-app-store-link" : "https://apps.apple.com/app/id3133333",
                "android-app-store-link" : "https://play.google.com/store/apps/details?id=com.example",
                "is-first-party-sticker" : 0 | 1 # integer 
            },
            "mime_type": "image/webp",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
        }  
    }]
}

Pesan yang Dibuat dari Iklan yang Mengeklik ke WhatsApp

{
   "messages":[{
      "from":"12345678",
      "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "image":{
         "id":"b1c68f38-8734-4ad3-b4a1-ef0c10d683",
         "mime_type":"image/jpeg",
         "sha256":"29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db"
         "caption": "Check out my product!",
      },
      "timestamp":"1521497954",
      "type":"image",
      "referral" : {
        "headline": "Our new product",
        "body" : "This is a great product",
        "source_type": "<SOURCE_TYPE>",
        "source_id": "<SOURCE_ID>",
        "source_url": "<SOURCE_URL>", //for the moment, this will always be a Facebook owned domain
        "video": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45",
        "ctwa_clid": "<CTWA_CLID>",
      }     
    }
  }]
}

Lihat informasi selengkapnya tentang properti referral.

Contoh: Pesan yang Tidak Didukung

Adalah mungkin untuk menerima notifikasi panggilan balik unknown. Berikut ini adalah contoh jenis pesan yang tidak didukung yang diterima dari pelanggan.

{
  "contacts": [{
		"profile": {
			"name": "Kerry Fisher"
		},
		"wa_id": "16315551234"
	}],
  "messages": [{
		"errors": [{
			"code": 501,
			"details": "Message type is not currently supported",
			"title": "Unknown message type"
		}],
		"from": "16315551234",
		"id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB",
		"timestamp": "1531933468",
		"type": "unknown"
	}]
}

Pesan yang Diteruskan

Anda dapat melihat apakah pesan yang Anda terima telah diteruskan atau sering diteruskan. Ini adalah notifikasi untuk pesan yang diteruskan:

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "context": {
      "forwarded": true
    },
    "from": "16315558011",
    "id": "ABGGFmkiWVVPAgo-sOGh7pv13wVJ",
    "text": {
      "body": "Party at Dotty's tonight!"
    },
    "timestamp": "1593068329",
    "type": "text"
  }]
}

Ini adalah notifikasi untuk pesan yang sering diteruskan:

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "context": {
      "frequently_forwarded": true
    },
    "from": "16315558011",
    "id": "ABGGFmkiWVVPAgo-sBTHfS3swNIl",
    "timestamp": "1593068225",
    "type": "video",
    "video": {
      "id": "e144be57-12b1-4035-a520-703fcc87ef45",
    "mime_type": "video/mp4",
    "sha256": "02c4e68a4f0d6af5ec6ef02120e20d15f520a4dd473b535abec1aab175c4e8b9"
    }
  }]
}

Notifikasi Keamanan Diaktifkan

Jika parameter show_security_notifications diatur ke true di pengaturan aplikasi, semua notifikasi pesan masuk akan menyertakan informasi berikut tentang identitas pengguna yang terdapat di dalam objek identity:

{
  "contacts": [{
		"profile": {
			"name": "Kerry Fisher"
		},
		"wa_id": "16315551234"
	}],
   "messages": [{
        "from": "16315553601",
        "id": "ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
        "identity": {
            "acknowledged": true,
            "created_timestamp": 1602532300000,
            "hash": "Sjvjlx8G6Z0="
        },
        "text": {
            "body": "Hi from new number 3601"
        },
        "timestamp": "1602532300",
        "type": "text"
    }]
}

Pesan dari Klik Tombol Balas Cepat

Saat pelanggan Anda mengeklik tombol balasan cepat, tanggapan dikirim. Di bawah ini adalah contoh format callback. Catatan: Pelanggan mungkin tidak mengeklik tombol dan membalas pesan interaktif atau hanya mengirimi Anda pesan. Pastikan Anda juga dapat mendukung jenis skenario ini. Lihat dokumentasi Webhooks untuk informasi selengkapnya. 
{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16505551234"
        }
    ],
    "messages": [
        {
            "button": {
                "payload": "No-Button-Payload",
                "text": "No"
            },
            "context": {
                "from": "16315558007",
                "id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
            },
            "from": "16505551234",
            "id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
            "timestamp": "1591210827",
            "type": "button"
        }
    ]
    # If there are any errors, an errors field (array) will be present        
    "errors": [ { ... } ]
}

Balasan Masuk untuk Pesan Terkirim

Pengguna dapat menanggapi pesan tertentu di WhatsApp. Agar bisnis memahami konteks balasan pesan, kami menyertakan objek context. Objek context ini menyediakan id dari pesan yang dibalas oleh pelanggan, ID WhatsApp pengirim pesan asli, dan ID untuk produk apa pun yang mungkin dirujuk oleh pelanggan.

Membalas Pesan berisi informasi selengkapnya.

Contoh: Pelanggan Membalas Pesan Anda

Berikut ini adalah contoh pesan masuk yang merupakan balasan untuk pesan yang Anda kirim. Lihat bagian objek context di bawah untuk informasi selengkapnya.

{
  "contacts": [ {
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  } ],
   "messages":[{
      "context":{
         "from":"16315558011",
         "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf"
         },
      "from":"16315551234",
      "id":"gBGGFlA5FpafAgkOuJbRq54qwbM",
      "text":{"body":"Yes, count me in!"},
      "timestamp":"1521499915",
      "type":"text"
  }]
}

Kolom text bersifat opsional untuk pesan media. Jika ada, nilai text adalah keterangan media yang dikirim atau isi tanggapan, jika tanggapannya berupa pesan teks.

Contoh: Pelanggan Membalas Pesan berisi Daftar

{
   "messages": [ {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
          "type": "list_reply",
          "list_reply": {
            "title": "row-title-content-here",
            "id": "unique-row-identifier-here",
            "description": "row-description-content-here"
          }
      }
   }

Contoh: Pelanggan Membalas Pesan dari Tombol Balas

{
  "messages": [ 
    {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
        "type": "button_reply",
        "button_reply": {
          "id": "unique-button-identifier",
          "title": "button-text"
        }
      } # end interactive node
    } # end message item
  ] # end messages array
}

Contoh: Pelanggan Meminta Informasi Tentang Produk Tertentu

{
  "contacts": [
    {
      "profile": {
        "name": "customer-name"
      },
      "wa_id": "customer-whatsapp-ID"
    }
  ],
  "messages": [
    {
      "from": "customer-whatsapp-ID",
      "id": "message-ID",
      "text": {
        "body": "Can I get this in another color?"
      },
      "context": {
        "referred_product": {
          "catalog_id": "catalog-ID",
          "product_retailer_id": "product-ID"
        }
      },
      "timestamp": "message-received-timestamp",
      "type": "text"
    }
  ]
}

Contoh: Pelanggan melakukan pemesanan setelah menerima Pesan Multiproduk atau Produk Tunggal

{
   "messages": [ {
      "from": "customer-whatsapp-id",
      "group_id": "group-id",
      "id": "message-ID",
      "timestamp": "message-timestamp",
      "type": "order"
      "order": {
         "catalog_id": "catalog_id",
         "product_items": [
            {
            "product_retailer_id":"product-ID",
            "quantity":"number-of-items",
            "item_price":"unitary-price-of-item",
            "currency":"price-currency"
            },
                 ...
         ],
         "text":"text-message-sent-along-with-the-order"
      }
   }
}

Pesan Sistem Masuk

Pesan sistem dibuat oleh sistem ketika beberapa peristiwa terjadi.

Contoh: Pengguna Berganti Nomor Telepon

Jika parameter notify_user_change_number diatur ke true di pengaturan aplikasi, Anda akan menerima pesan sistem masuk ketika pengguna mengubah nomor teleponnya.

{
    "messages": [
        {
            "from": "16315558889",
            "id": "ABGGFjFVWIifAzNzeXMtMTYzMTU1NTg4ODlAcy53aGF0c2FwcC5uZXQtMTU3NDA4MDEwMjIxMy1jaGFuZ2U",
            "system": {
                "body": "‎User A changed from ‎+1 (631) 555-8889 to ‎+1 (631) 555-8890‎",
                "new_wa_id": "16315558890",
                "type": "user_changed_number"
            },
            "timestamp": "1574080102",
            "type": "system"
        }
    ]
}

Contoh: Seorang Pengguna Berpotensi Telah Berubah

Jika parameter show_security_notifications diatur ke true di pengaturan aplikasi, Anda akan menerima pesan sistem masuk ketika pengguna (dalam percakapan dengan Anda) berpotensi berubah di WhatsApp.

Sampai notifikasi ini diakui menggunakan endpoint identity, semua pesan keluar ke pengguna ini akan diblokir. Pesan masuk akan terus diterima seperti yang diharapkan.

{
    "messages": [
        {
            "from": "16315553601",
            "id": "ABGGFjFVU2AfAzVzeXMtMTYzMTU1NTM2MDFAcy53aGF0c2FwcC5uZXQtMTYwMjUzNTM1NjMzMi1pZGVudGl0eQ",
            "system": {
  		"body": "Test security code change",
                "identity": "Rc/eg9Rl0JA=",
                "type": "user_identity_changed",
                "user": "16315553601"
            },
            "timestamp": "1602535356",
            "type": "system"
        }
    ]
}

Jenis Pesan Sistem

Jenis Pesan SistemDeskripsi

user_changed_number

Nomor telepon pengguna berubah

user_identity_changed

Pengguna mungkin sudah berganti di WhatsApp

Menyebutkan Pengguna dalam Pesan

Saat Anda mengirim pesan yang menyebutkan ID WhatsApp tertentu secara langsung dan seseorang membalas pesan itu, Anda akan melihat ID yang disebutkan di objek context dan di array mentions. Karena lebih dari satu nomor telepon dapat disebutkan, kolom mentions adalah array nomor telepon, meskipun hanya satu nomor telepon yang disebutkan.

Contoh: Pelanggan Membalas Pesan

Berikut ini adalah contoh pelanggan membalas pesan yang berisi penyebutan. Objek context berisi angka yang disebutkan dalam pesan asli. Balasan di objek text menyebutkan angka yang sama lagi.

{   
  "messages": [{
    "context": {
      "from": "16315555544",
      "id": "gBGGFlA5FpafAgkOuJbRq54qwbM",
      "mentions": [
        "16315551000",
        "16315551099"
      ]
    },
    "from": "16315551234 ",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1504902988",
    "text": {
      "body": "@16315551000 and @16315551099 are mentioned"
    },
    "type": "text"
  }]
}