WhatsApp Mesaj API Dokümantasyonu

Genel Bakış

VatanSMS.com WhatsApp Mesaj API, işletmelerin ve geliştiricilerin WhatsApp üzerinden mesaj gönderimi, oturum yönetimi ve entegrasyon süreçlerini yönetmesini sağlayan kapsamlı bir teknik altyapıdır. Bu dokümantasyon, kurumsal mesajlaşma operasyonlarını daha düzenli ve ölçeklenebilir hale getirmek için gerekli kullanım adımlarını bir araya getirir.

Kurumsal kullanım, resmî başvuru süreci ve onaylı hesap yapısı hakkında daha kapsamlı bilgi almak isterseniz WhatsApp Business API çözümü sayfasını inceleyebilirsiniz. Eğer çok kanallı iletişim kurgusunda SMS tarafını da değerlendirmek istiyorsanız toplu SMS hizmeti sayfası ile SMS ve WhatsApp kullanım senaryolarını birlikte karşılaştırabilirsiniz.

API Kullanım Amacı

WhatsApp Mesaj API'si, işletmelerin ve geliştiricilerin WhatsApp üzerinden tekil veya çoklu mesaj gönderimi, bildirim akışları ve entegrasyon senaryolarını yönetmesini sağlayan bir araçtır. Bu API; müşteri iletişimini otomatikleştirmek, destek süreçlerini güçlendirmek ve operasyonel mesajlaşmayı merkezi şekilde yönetmek amacıyla kullanılır.

Temel Amaçlar ve Kullanım Alanları:

  • Müşteri Hizmetleri: İşletmeler, müşterilerle hızlı ve etkili bir şekilde iletişim kurarak müşteri memnuniyetini artırabilir.
  • Otomatik Bildirimler: Sipariş durumu, teslimat bilgileri, randevu hatırlatmaları gibi önemli bildirimler otomatik olarak gönderilebilir.
  • Pazarlama ve Promosyonlar: Ürün tanıtımları, indirimler ve özel teklifler toplu mesajlarla geniş kitlelere ulaştırılabilir.
  • Anket ve Geri Bildirim: Müşteri memnuniyeti anketleri ve geri bildirim talepleri toplu mesajlar aracılığıyla toplanabilir.
  • Etkinlik Yönetimi: Etkinlik davetleri ve hatırlatmalar toplu mesajlarla katılımcılara iletilebilir.

WhatsApp Mesaj API'si, özellikle yüksek hacimli müşteri iletişimi yürüten işletmeler için daha düzenli ve izlenebilir bir mesajlaşma süreci sağlar. Teknik ekipler bu yapı sayesinde entegrasyon, oturum takibi ve gönderim operasyonlarını tek dokümantasyon üzerinden yönetebilir.

Yazılım entegrasyonuna ek olarak hazır panel üzerinden kullanım arıyorsanız WhatsApp toplu mesaj programı sayfasına, fiyat ve paket yapısını değerlendirmek isterseniz WhatsApp Business API fiyatları sayfasına geçebilirsiniz.

WhatsApp Mesaj API Özellikleri

API, kullanıcılara aşağıdaki başlıca özellikleri sunar:

  • Mesaj Gönderme: WhatsApp üzerinden bireysel veya toplu mesaj gönderimi yapabilirsiniz.
  • Giriş ve Doğrulama: Kullanıcıların telefon numaraları veya QR kodları ile giriş yapmalarını sağlar.
  • Profil Bilgileri: Kullanıcıların WhatsApp profil resimlerini ve diğer bilgilerini alabilirsiniz.
  • Cihaz Yönetimi: Kullanıcıların bağlı oldukları cihazları yönetme ve listeleme imkanını sunar.

Bu dokümantasyon, API'nin nasıl kullanılacağını ve her bir uç noktanın işlevselliğini detaylandırmaktadır. Tüm API istekleri, güvenli bir şekilde kimlik doğrulama bilgileri ile yapılmalıdır.

Authorization

API'ye erişim sağlamak için gerekli olan kimlik doğrulama bilgileri ve başlıklar hakkında bilgi vermektedir.

Erişim Bilgileri

VatanSMS.com WhatsApp Mesaj API'ye erişim sağlamak için her bir istekte aşağıdaki başlıklar kullanılmalıdır:

  • client-id: API erişim anahtarınız. Bu anahtar, size özel olarak sağlanır ve API'ye yapılan isteklerde kimliğinizi doğrulamak için kullanılır.
  • client-secret: API erişim gizli anahtarınız. Bu anahtar, API'ye yapılan isteklerin güvenliğini sağlamak için kullanılır ve gizli tutulmalıdır.

Kendi başlık bilgilerinizi VatanSMS.com panelinizden öğrenebilirsiniz. Bu başlıklar, her bir API isteği ile birlikte gönderilmelidir.

Örneğin, bir POST isteği yaparken:

POST /login/phone
Host: api.VatanSMS.com
client-id: <your-client-id>
client-secret: <your-client-secret>

Bu kimlik doğrulama bilgileri, API'nin güvenliğini ve yetkilendirilmiş erişimini sağlamak için kritik öneme sahiptir. Bu nedenle, bu bilgileri güvenli bir şekilde saklamalı ve yetkisiz kişilerle paylaşmamalısınız.

Eğer client-id veya client-secret bilgileriniz kaybolursa veya yetkisiz erişimden şüpheleniyorsanız, derhal VatanSMS.com destek ekibi ile iletişime geçmelisiniz.

Canlı Ortam Bilgileri

API'nin canlı ortam bilgileri:

Endpoint Bilgileri

  • Canlı Ortam: https://api.vatansms.com/api/whatsapp/v1

API Metodları

Her bir API metodunun detayları ve kullanım bilgileri aşağıda yer almaktadır.

Telefon ile Giriş Yapma

Whatsapp'a telefon numarası ile bağlanmak için kullanabilirsiniz.

URL:

POST /login/phone

Açıklama:

Kullanıcının telefon numarası ile giriş yapmasını sağlar.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

İstek Gövdesi:

Parametre Tür Örnek Değer Açıklama
phone String +90xxxxxxxxxx Giriş yapılacak whatsapp telefon numarasını giriniz

Örnek Yanıt (JSON):

{
    "code": 200,
    "status": "success",
    "description": "İşlem başarılı!",
    "data": {
        "code": "HP61-VKLZ",
        "regId": "3641473184"
    }
}

Servisten başarılı bir şekil de istek dönerse size data içerisinde code ve regId dönecektir. "code" değerini whatsapp da gelen bildirime tıklayıp ilgili yere 30 saniye içerisinde girmelisiniz. "regId" değeri ile Aktif Giriş Kontrolü yada Giriş Kontrolü servisleri üzerinden kullanıcının giriş yapıp yapmadığını kontrol edebilirsiniz.

QR Kodu ile Giriş Yapma

URL:

POST /login/qr

Açıklama:

Kullanıcının QR kodu ile giriş yapmasını sağlar.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

Örnek Yanıt:

{
    "code": 200,
    "status": "success",
    "description": "İşlem başarılı!",
    "data": {
        "qr": "2@NcanFexWlvJeLPSJPnHWwsan+I15DswHPWiBNhGdp6WrnBYiDlwjwuGgpKIUL8azkRjABhp4odFEgQ==,INWPagDaoB9t99EYSu3uJuinBtsmktGdQU3nv+JKsSM=,KHDwJmljYg4nbRHTuqxYMrsGUK7QU/j1qooOEgwLWmo=,k/xPMyRWh5nRU9gp25SLgPGmf9vgqD6qGcK1nhuDyTk=",
        "regId": "578028480"
    }
}

Servisten başarılı bir şekil de istek dönerse size data içerisinde qr ve regId dönecektir. QR kodunu whatsapp uygulaması üzerinden 30 saniye içerisinde okutmalısınız. "regId" değeri ile Aktif Giriş Kontrolü yada Giriş Kontrolü servisleri üzerinden kullanıcının giriş yapıp yapmadığını kontrol edebilirsiniz.

Aktif Giriş Kontrolü

URL:

POST /login/check/active

Açıklama:

Kullanıcının aktif giriş durumunu kontrol eder. Eğer kullanıcı giriş yapmışsa 200 dönecektir. Bu servis genel de bir kez giriş yaptıktan sonra tekrar kontrol için kullanılır. Eğer kullanıcı ilk defa sisteme giriş yapacaksa Giriş Kontrolü servisini kullanın.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

İstek Gövdesi:

Parametre Tür Örnek Değer Açıklama
reg_id BigInteger xxxxxxxxxx Qr Kodu ile Giriş Yapma yada Telefon ile Giriş Yapma servislerinden dönen regId değerini gönderiniz

Örnek Yanıt (JSON):

{
    "code": 200,
    "status": "success",
    "description": "İşlem başarılı!",
    "data": {
        "device_number": "905xxxxxxxxx",
        "platform": "android",
        "state": "1",
        "user_name": "Vatan SMS",
        "j_id": "905xxxxxxxxx:97@s.whatsapp.net"
    },
    "is_connect": true,
    "message": "device connected"
}

Giriş Kontrolü

URL:

POST /login/check

Açıklama:

Kullanıcının giriş durumunu kontrol eder. Eğer kullanıcı sisteme ilk defa giriş yapacaksa bu servisi kullanmanız önerilir. İsteklere 30 saniye içerisinde cevap verilir. Eğer 30 saniye içerisinde sistem bir giriş algılamadıysa 400 döner. Eğer bir giriş algılarsa 200 dönecektir.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

İstek Gövdesi:

Parametre Tür Örnek Değer Açıklama
reg_id BigInteger xxxxxxxxxx Qr Kodu ile Giriş Yapma yada Telefon ile Giriş Yapma servislerinden dönen regId değerini gönderiniz

Örnek Yanıt (JSON):

{
    "code": 200,
    "status": "success",
    "description": "İşlem başarılı!",
    "data": {
        "is_connect": true,
        "message": "device connected"
    }
}

Mesaj Gönderme

URL:

POST /messages/send

Açıklama:

Mesaj gönderir.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

İstek Gövdesi:

Parametre Tür Örnek Değer Açıklama
reg_id BigInteger xxxxxxxxxx Kullanıcının kayıt kimliği. Qr Kodu ile Giriş Yapma yada Telefon ile Giriş Yapma servislerinden dönen regId değerini gönderiniz
to String +90xxxxxxxxxx Mesajın gönderileceği telefon numarası.
message String test mesaj içeriği Gönderilecek mesaj içeriği.
attachment File - Eklenmek istenen dosya (isteğe bağlı). Kabul edilen dosya türleri: pdf, doc, docx, ppt, pptx, xls, xlsx, jpeg, jpg, png
send_speed Integer 1 Mesaj gönderim hızı. 1,2,3,4 değerlerinden birini alır. 1 en hızlı değer olup 4 en yavaş değerdir.
report_id BigInteger 1 Rapor kimliği (isteğe bağlı). Callback adresinize bildirim yapılırken bu değer ile birlikte gönderim yapılır.

Örnek Yanıt:

{
    "code": 200,
    "status": "success",
    "description": "Mesajlarınız Gönderildi"
}

Birden Fazla Alıcıya Mesaj Gönderme

URL:

POST /messages/send/oneToN

Açıklama:

Birden fazla alıcıya mesaj gönderir.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

İstek Gövdesi:

Parametre Tür Örnek Değer Açıklama
reg_id BigInteger xxxxxxxxxx Kullanıcının kayıt kimliği. Qr Kodu ile Giriş Yapma yada Telefon ile Giriş Yapma servislerinden dönen regId değerini gönderiniz
to String +90xxxxxxxxxx, +90xxxxxxxxxx Mesajın gönderileceği telefon numaraları, virgülle ayrılmış şekilde.
message String test mesaj içeriği Gönderilecek mesaj içeriği.
attachment File - Eklenmek istenen dosya (isteğe bağlı). Kabul edilen dosya türleri: pdf, doc, docx, ppt, pptx, xls, xlsx, jpeg, jpg, png
send_speed Integer 1 Mesaj gönderim hızı. 1,2,3,4 değerlerinden birini alır. 1 en hızlı değer olup 4 en yavaş değerdir.
report_id BigInteger 1 Rapor kimliği (isteğe bağlı). Callback adresinize bildirim yapılırken bu değer ile birlikte gönderim yapılır.

Örnek Yanıt:

{
    "code": 200,
    "status": "success",
    "description": "Mesajlarınız Gönderildi"
}

Çoklu Mesaj Gönderme

URL:

POST /messages/send/nToN

Açıklama:

Çoklu mesaj gönderir.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

İstek Gövdesi:

Parametre Tür Örnek Değer Açıklama
reg_id BigInteger xxxxxxxxxx Kullanıcının kayıt kimliği. Qr Kodu ile Giriş Yapma yada Telefon ile Giriş Yapma servislerinden dönen regId değerini gönderiniz
n_to_n Array [{"to": "+905459260314","message": "test mesaj 1"},{"to": "+903222450353","message": "test mesaj 2"}] Birden fazla alıcı ve mesaj içeren JSON dizisi.
to: mesajın gönderileceği whatsapp numarası, message: mesaj içeriğidir.
attachment File - Eklenmek istenen dosya (isteğe bağlı). Kabul edilen dosya türleri: pdf, doc, docx, ppt, pptx, xls, xlsx, jpeg, jpg, png
send_speed Integer 1 Mesaj gönderim hızı. 1,2,3,4 değerlerinden birini alır. 1 en hızlı değer olup 4 en yavaş değerdir.
report_id BigInteger 1 Rapor kimliği (isteğe bağlı). Callback adresinize bildirim yapılırken bu değer ile birlikte gönderim yapılır.

Örnek Yanıt:

{
    "code": 200,
    "status": "success",
    "description": "Mesajlarınız Gönderildi"
}

Profil Resmi Alma

URL:

POST /profile-picture

Açıklama:

Kullanıcının profil resmini alır.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

İstek Gövdesi:

Parametre Tür Örnek Değer Açıklama
reg_id String xxxxxxxxxx Kullanıcının kayıt kimliği. Qr Kodu ile Giriş Yapma yada Telefon ile Giriş Yapma servislerinden dönen regId değerini gönderiniz

Örnek Yanıt:

{
    "code": 200,
    "status": "success",
    "description": "İşlem başarılı",
    "data": {
        "image": "https://pps.whatsapp.net/v/"
    }
}

Çıkış Yapma

URL:

POST /logout

Açıklama:

Kullanıcının oturumunu kapatır.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

İstek Gövdesi:

Parametre Tür Örnek Değer Açıklama
reg_id String xxxxxxxxxx Kullanıcının kayıt kimliği. Qr Kodu ile Giriş Yapma yada Telefon ile Giriş Yapma servislerinden dönen regId değerini gönderiniz

Örnek Yanıt:

{
    "code": 200,
    "status": "success",
    "description": "Cihazdan çıkış yapıldı"
}

Cihazları Alma

URL:

GET /devices

Açıklama:

Kullanıcının cihazlarını listeler.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

Örnek Yanıt:

{
    "code": 200,
    "status": "success",
    "description": "Bağlı cihazlarınız listelendi!",
    "data": [
        {
            "reg_id": "2953401050",
            "sender": "905xxxxxxxxx",
            "platform": "android",
            "user_name": "Vatan SMS",
            "profile_picture": "https://pps.whatsapp.net/v/",
            "created_at": "2024-05-29T14:13:28.000000Z"
        }
    ]
}

Callback İstekleri

URL:

POST VatanSMS.com panelinizde tanımlamanız gerekmektedir.

Açıklama:

VatanSMS.com panelinizde tanımladığınız callback adresine eğer mesaj gönderim servislerinden herhangi birini kullanırsanız sistem tarafından bildirim POST olarak JSON formatında gönderilir.

Başlıklar:

client-secret: API erişim anahtarınız
client-id: API erişim gizli anahtarınız

Bildirim Gövdesi:

Parametre Tür Örnek Değer Açıklama
callback_data BigInteger 33 Mesaj gönderim servislerini kullanırken gönderdiğiniz report_id değeridir.
status Integer 2 Eğer mesaj başarılı bir şekilde gönderildiyse "1" gönderilir. Eğer mesaj gönderiminde bir hata oluştuysa "2" olarak gönderilir.
phone BigInteger 90xxxxxxxxxx Mesajın gönderildiği telefon numarasıdır.
content string test mesaj içeriği Mesaj içeriğidir.
send_time datetime 2024-05-20 14:49:55 +0300 +03 Mesajın gönderilme zamanıdır.

Örnek Bildirim İçeriği :

{
   "callback_data":"33",
   "status":"2",
   "phone":"90xxxxxxxxxx",
   "content":"vatansmstest 1",
   "send_time":"2024-05-20 14:49:55 +0300 +03"
}