ruby_whatsapp_sdk

Ruby Whatsapp SDK

SDK menyediakan satu set operasi dan kelas untuk menggunakan WhatsApp API. Kirim stiker, pesan, audio, video, lokasi, bereaksi dan balas pesan atau hanya meminta nomor telepon melalui perpustakaan ini dalam beberapa langkah!

Demo

Messageapidemo.mov

Periksa Repositori Contoh Ruby on Rails Whatsapp yang menggunakan pustaka ini untuk mengirim pesan.

Instalasi

Tambahkan baris ini ke gemfile aplikasi Anda:

 gem 'whatsapp_sdk'

Dan kemudian mengeksekusi:

 $ bundle

Atau instal sendiri sebagai:

 $ gem install whatsapp_sdk

Awal yang cepat

Ada tiga sumber daya utama, Messages , Media , dan PhoneNumbers . Messages memungkinkan pengguna untuk mengirim pesan apa pun (teks, audio, lokasi, video, gambar, dll.). Media memungkinkan pengguna untuk mengelola media, dan Phone Numbers memungkinkan klien untuk menanyakan nomor telepon terkait.

Untuk menggunakan Messages , Media , atau PhoneNumbers , Anda perlu menginisialisasi Client yang berisi informasi auth. Ada dua cara untuk melakukannya.

Opsi 1) Gunakan inisialisasi

 # config/initializers/whatsapp_sdk.rb
WhatsappSdk . configure do | config |
  config . access_token = ACCESS_TOKEN
  config . api_version = API_VERSION
  config . logger = Logger . new ( STDOUT ) # optional, Faraday logger to attach
  config . logger_options = { bodies : true } # optional, they are all valid logger_options for Faraday
end

Catatan:

• Secara opsional, Anda dapat menentukan versi API yang diinginkan untuk digunakan (default ke versi terbaru jika dihilangkan). Versi API yang tersedia dapat ditemukan di sini.
• Anda dapat memasang logger. Rincian lebih lanjut tentang opsi Logger Faraday ada di sini.

Opsi 2) Buat instance Client :

 # without
client = WhatsappSdk :: Api :: Client . new ( "<ACCESS TOKEN>" ) # replace this with a valid access token

# OR optionally use a logger, api_version and
logger = Logger . new ( STDOUT )
logger_options = { bodies : true }
client = WhatsappSdk :: Api :: Client . new ( "<ACCESS TOKEN>" , "<API VERSION>" , logger , logger_options ) 

Siapkan aplikasi meta

1) Buat aplikasi bisnis meta

2) Tambahkan whatsapp ke aplikasi Anda

3) Tambahkan nomor telepon ke akun Anda

Coba kirim pesan ke ponsel Anda di UI.

4) Salin access_token, sender_id, Business_id dan penerima_number

5) Gunakan permata untuk berinteraksi dengan whatsapp

Contoh:

1. Instal permata dengan menjalankan gem install whatsapp_sdk di permata.
2. Buka terminal IRB dengan menjalankan irb
3. require "whatsapp_sdk"
4. Siapkan ACCESS_TOKEN , SENDER_ID , BUSINESS_ID dan RECIPIENT_NUMBER dalam variabel.

 ACCESS_TOKEN = "EAAZAvvr0DZBs0BABRLF8zohP5Epc6pyNu"
BUSINESS_ID = 1213141516171819
SENDER_ID = 1234567891011
RECIPIENT_NUMBER = 12398765432

5. Konfigurasikan klien dengan menjalankan

 WhatsappSdk . configure do | config |
  config . access_token = ACCESS_TOKEN
end

6. Coba API Nomor Telepon atau API Pesan

API Nomor Telepon

 registered_number = client . phone_numbers . registered_number ( SENDER_ID )

Pesan API

 message_sent = client . messages . send_text ( sender_id : SENDER_ID , recipient_number : RECIPIENT_NUMBER ,
                                      message : "Hey there! it's Whatsapp Ruby SDK" )

Periksa file contoh.rb untuk lebih banyak contoh.

Menyelinap mengintip

 client = WhatsappSdk :: Api :: Client . new ( "<ACCESS TOKEN>" ) # replace this with a valid access token

client . phone_numbers . register_number ( SENDER_ID , 123456 ) # register the phone number to uplaod media and send message from.

# send a text and a location
client . messages . send_text ( sender_id : SENDER_ID , recipient_number : RECIPIENT_NUMBER , message : "Hey there! it's Whatsapp Ruby SDK" )

client . messages . send_location ( sender_id : SENDER_ID , recipient_number : RECIPIENT_NUMBER , longitude : - 75.6898604 , latitude : 45.4192206 , name : "Ignacio" , address : "My house" )

# upload a photo and send it
image = client . media . upload ( sender_id : SENDER_ID , file_path : "test/fixtures/assets/whatsapp.png" , type : "image/png" ) image = client . media . get ( media_id : uploaded_media . id )
client . messages . send_image ( sender_id : SENDER_ID , recipient_number : RECIPIENT_NUMBER , image_id : image . id )

# upload a sticker and send it
sticker = client . media . upload ( sender_id : SENDER_ID , file_path : "test/fixtures/assets/sticker.webp" , type : "image/webp" )
client . messages . send_sticker ( sender_id : SENDER_ID , recipient_number : RECIPIENT_NUMBER , sticker_id : sticker . id ) 

Lebah

Template

 # Get list of templates
client . templates . list ( business_id : BUSINESS_ID )

# Get Message Template Namespace
# The message template namespace is required to send messages using the message templates.
client . templates . get_message_template_namespace ( business_id : BUSINESS_ID )

# Create a template
client . templates . create (
  business_id : BUSINESS_ID , name : "seasonal_promotion" , language : "en_US" , category : "MARKETING" ,
  components_json : components_json , allow_category_change : true
)

# Delete a template
client . templates . delete ( business_id : BUSINESS_ID , name : "my_name" ) # delete by name

API Profil Bisnis

 # Get the details of your business
client . business_profiles . get ( phone_number_id )

# Update the details of your business
client . business_profiles . update ( phone_number_id : SENDER_ID , params : { about : "A very cool business" } )

API Nomor Telepon

 # Get the list of phone numbers registered
client . phone_numbers . list ( business_id )

# Get the a phone number by id
client . phone_numbers . get ( phone_number_id )

# Register a phone number
client . phone_numbers . register_number ( phone_number_id , pin )

# Deregister a phone number
client . phone_numbers . deregister_number ( phone_number_id )

API Media

 # Upload a media
client . media . upload ( sender_id : SENDER_ID , file_path : "tmp/whatsapp.png" , type : "image/png" )

# Get a media
media = client . media . get ( media_id : MEDIA_ID )

# Download media
client . media . download ( url : MEDIA_URL , file_path : 'tmp/downloaded_whatsapp.png' , media_type : "image/png" )

# Delete a media
client . media . delete ( media_id : MEDIA_ID )

Pesan API

 # Send a text message
client . messages . send_text ( sender_id : 1234 , recipient_number : 112345678 , message : "hola" )

# Read a message
client . messages . read_message ( sender_id : 1234 , message_id : "wamid.HBgLMTM0M12345678910=" )

# Note: To get the `message_id` you can set up [Webhooks](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components) that will listen and fire an event when a message is received.

# Send a reaction to message
#   To send a reaction to a message, you need to obtain the message id and look for the emoji's unicode you want to use.
client . messages . send_reaction ( sender_id : 123_123 , recipient_number : 56_789 , message_id : "12345" , emoji : " u{1f550} " )
client . messages . send_reaction ( sender_id : 123_123 , recipient_number : 56_789 , message_id : "12345" , emoji : "⛄️" )

# Reply to a message
# To reply to a message, just include the id of the message in the `client.messages` methods. For example, to reply to a text message include the following:
client . messages . send_text ( sender_id : 123_123 , recipient_number : 56_789 , message : "I'm a reply" , message_id : "wamid.1234" )

# Send a location message
client . messages . send_location (
  sender_id : 123123 , recipient_number : 56789 ,
  longitude : 45.4215 , latitude : 75.6972 , name : "nacho" , address : "141 cooper street"
)

# Send an image message
#  It uses a link or an image_id.
#  with a link
client . messages . send_image ( sender_id : 123123 , recipient_number : 56789 , link : "image_link" , caption : "Ignacio Chiazzo Profile" )

# with an image id
client . messages . send_image ( sender_id : 123123 , recipient_number : 56789 , image_id : "1234" , caption : "Ignacio Chiazzo Profile" )


# Send an audio message
# It uses a link or an audio_id.
# with a link
client . messages . send_audio ( sender_id : 123123 , recipient_number : 56789 , link : "audio_link" )

# with an audio id
client . messages . send_audio ( sender_id : 123123 , recipient_number : 56789 , audio_id : "1234" )

# Send a document message
# It uses a link or a document_id.
# with a link
client . messages . send_document ( sender_id : 123123 , recipient_number : 56789 , link : "document_link" , caption : "Ignacio Chiazzo" )

# with a document id
client . messages . send_document ( sender_id : 123123 , recipient_number : 56789 , document_id : "1234" , caption : "Ignacio Chiazzo" )
# Note, you can specify the filename via argument [`filename`](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages). 

# Send a sticker message
#  It could use a link or a sticker_id.
#  with a link
client . messages . send_sticker ( sender_id : 123123 , recipient_number : 56789 , link : "link" )

# with a sticker_id
client . messages . send_sticker ( sender_id : 123123 , recipient_number : 56789 , sticker_id : "1234" )

# Send contacts message
# To send a contact, you need to create a Contact instance object that contain objects embedded like `addresses`, `birthday`, `emails`, `name`, `org`. See this [guide](/test/contact_helper.rb) to learn how to create contacts objects.
client . messages . send_contacts ( sender_id : 123123 , recipient_number : 56789 , contacts : [ create_contact ( params ) ] )

# Alternatively, you could pass a plain json like this:
client . messages . send_contacts ( sender_id : 123123 , recipient_number : 56789 , contacts_json : { ... } )

# Send a template message
# WhatsApp message templates are specific message formats that businesses use to send out notifications or customer care messages to people that have opted in to notifications. Messages can include appointment reminders, shipping information, issue resolution or payment updates.

# Before sending a message template, you need to create one. visit the [Official API Documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates)

Contoh Komponen

 currency = WhatsappSdk :: Resource :: Currency . new ( code : "USD" , amount : 1000 , fallback_value : "1000" )
date_time = WhatsappSdk :: Resource :: DateTime . new ( fallback_value : "2020-01-01T00:00:00Z" )
media_component = WhatsappSdk :: Resource :: MediaComponent . new ( type : "image" , link : "http(s)://URL" )
location = WhatsappSdk :: Resource :: Location . new (
  latitude : 25.779510 , longitude : - 80.338631 , name : "miami store" , address : "820 nw 87th ave, miami, fl"
)

parameter_image = WhatsappSdk :: Resource :: ParameterObject . new ( type : "image" , image : media_component )
parameter_text = WhatsappSdk :: Resource :: ParameterObject . new ( type : "text" , text : "TEXT_STRING" )
parameter_currency = WhatsappSdk :: Resource :: ParameterObject . new ( type : "currency" , currency : currency )
parameter_date_time = WhatsappSdk :: Resource :: ParameterObject . new ( type : "date_time" , date_time : date_time )
parameter_location = WhatsappSdk :: Resource :: ParameterObject . new ( type : "location" , location : location )

header_component = WhatsappSdk :: Resource :: Component . new ( type : "header" , parameters : [ parameter_image ] )

body_component = WhatsappSdk :: Resource :: Component . new (
  type : "body" , 
  parameters : [ parameter_text , parameter_currency , parameter_date_time ]
)

button_component1 = WhatsappSdk :: Resource :: Component . new (
  type : "button" ,
  index : 0 ,
  sub_type : "quick_reply" ,
  parameters : [
    WhatsappSdk :: Resource :: ButtonParameter . new ( type : "payload" , payload : "PAYLOAD" )
  ]
)

button_component2 = WhatsappSdk :: Resource :: Component . new (
  type : "button" ,
  index : 1 ,
  sub_type : "quick_reply" ,
  parameters : [
    WhatsappSdk :: Resource :: ButtonParameter . new ( type : "payload" , payload : "PAYLOAD" )
  ]
)

location_component = WhatsappSdk :: Resource :: Component . new ( type : "header" , parameters : [ parameter_location ] )
client . messages . send_template (
  sender_id : 12_345 , recipient_number : 12345678 , name : "hello_world" , language : "en_US" , components : [ ... ]
)

Atau, Anda bisa melewati JSON biasa seperti ini:

 client . messages . send_template ( sender_id : 12_345 , recipient_number : 12345678 , name : "hello_world" , language : "en_US" , components_json : [ { ... } ] )

Kirim pesan interaktif Kunjungi dokumentasi API resmi

Daftar contoh pesan

 interactive_header = WhatsappSdk :: Resource :: InteractiveHeader . new ( type : "text" , text : "I am the header!" )
interactive_body = WhatsappSdk :: Resource :: InteractiveBody . new ( text : "I am the body!" )
interactive_footer = WhatsappSdk :: Resource :: InteractiveFooter . new ( text : "I am the footer!" )
interactive_action = WhatsappSdk :: Resource :: InteractiveAction . new ( type : "list_message" )

interactive_action . button = "I am the button CTA"

interactive_section_1 = WhatsappSdk :: Resource :: InteractiveActionSection . new ( title : "I am the section 1" )
interactive_section_1_row_1 = WhatsappSdk :: Resource :: InteractiveActionSectionRow . new (
  title : "I am the row 1 title" ,
  id : "section_1_row_1" ,
  description : "I am the optional section 1 row 1 description"
)
interactive_section_1 . add_row ( interactive_section_1_row_1 )
interactive_action . add_section ( interactive_section_1 )

interactive_list_messages = WhatsappSdk :: Resource :: Interactive . new (
  type : "list" ,
  header : interactive_header ,
  body : interactive_body ,
  footer : interactive_footer ,
  action : interactive_action
)

client . messages . send_interactive_list_messages (
  sender_id : SENDER_ID , recipient_number : RECIPIENT_NUMBER ,
  interactive : interactive_list_messages
)

Atau, Anda bisa melewati JSON biasa seperti ini:

 client . messages . send_interactive_list_messages (
  sender_id : 12_345 , recipient_number : 1234567890
  interactive_json : { ... }
)

Contoh tombol balas

 interactive_header = WhatsappSdk :: Resource :: InteractiveHeader . new ( type : "text" , text : "I am the header!" )
interactive_body = WhatsappSdk :: Resource :: InteractiveBody . new ( text : "I am the body!" )
interactive_footer = WhatsappSdk :: Resource :: InteractiveFooter . new ( text : "I am the footer!" )

interactive_action = WhatsappSdk :: Resource :: InteractiveAction . new ( type : "reply_button" )
interactive_reply_button_1 = WhatsappSdk :: Resource :: InteractiveActionReplyButton . new (
  title : "I am the reply button 1" ,
  id : "button_1"
)
interactive_action . add_reply_button ( interactive_reply_button_1 )

interactive_reply_button_2 = WhatsappSdk :: Resource :: InteractiveActionReplyButton . new (
  title : "I am the reply button 2" ,
  id : "button_2"
)
interactive_action . add_reply_button ( interactive_reply_button_2 )

interactive_reply_buttons = WhatsappSdk :: Resource :: Interactive . new (
  type : "reply_button" ,
  header : interactive_header ,
  body : interactive_body ,
  footer : interactive_footer ,
  action : interactive_action
)

client . messages . send_interactive_reply_buttons (
  sender_id : 12_345 , recipient_number : 1234567890 ,
  interactive : interactive_reply_buttons
)

Alternatif, Anda bisa melewati JSON biasa seperti ini:

 client . messages . send_interactive_reply_buttons (
  sender_id : 12_345 , recipient_number : 1234567890
  interactive_json : { ... }
)

Kesalahan

Jika API mengembalikan kesalahan maka pengecualian WhatsappSdk::Api::Responses::HttpResponseError dinaikkan. Objek berisi informasi yang dikembalikan oleh API cloud. Untuk informasi lebih lanjut tentang potensi kesalahan, periksa dokumentasi resmi.

Contoh

Kunjungi file contoh dengan contoh untuk memanggil API dalam satu file.

Whatsapp Cloud API

• Lihat dokumentasi resmi untuk WhatsApp Cloud API.
• Untuk harga, lihat dokumentasi resmi. Sampai hari ini, penawaran WhatsApp memiliki 1000 percakapan gratis per bulan.

Pemecahan masalah

Jika Anda mencoba mengirim pesan teks secara langsung tanpa templat pesan yang dibuat dan disetujui di panel kontrol meta Anda, Anda tidak dapat memulai obrolan dengan orang lain. Tetapi jika Anda menerima pesan sebelumnya, dimungkinkan untuk mengirim pesan.

Jika respons API masih success , tetapi pesannya tidak disampaikan:

• Pastikan perangkat yang Anda kirim pesan menggunakan versi WhatsApp yang didukung. Periksa dokumentasi. Coba juga balas pesan ke nomor yang Anda terdaftar di whatsapp Anda.
• Pastikan aplikasi meta Anda menggunakan versi API yang lebih besar dari atau sama dengan v.14 .
• Pastikan panel di dasbor Facebook tidak menampilkan kesalahan.

Catatan: Terkadang pesan ditunda; Lihat Dokumentasi Meta.

Perkembangan

Setelah memeriksa repo, jalankan bin/setup untuk menginstal dependensi. Kemudian, jalankan rake test untuk menjalankan tes.

Jalankan 'Bundle Exec Rake Instal' untuk menginstal permata ini ke mesin lokal Anda. Untuk merilis versi baru, perbarui nomor versi di version.rb , dan kemudian jalankan bundle exec rake release , yang akan membuat tag git untuk versi, Push Git Commits and Tag, dan tekan file .gem ke rubygems.org.

Jalankan semua tes

• Tes unit: Jalankan rake test
• Sorbet Typecheck: Jalankan srb tc
• Linters: bundle exec rubocop

Untuk memperbarui versi Cloud API, perbarui versi di lib/whatsapp_sdk/api/api_configuration.rb . Periksa cloud API Changelog untuk API Udpates.

Berkontribusi

Laporan bug dan permintaan tarik dipersilakan di GitHub di https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk proyek ini dimaksudkan untuk menjadi ruang perilaku yang aman dan ramah untuk kolaborasi, dan kontributor diharapkan untuk mematuhi kontributor kode perilaku perjanjian.

Jika Anda ingin fitur diimplementasikan dalam permata, silakan buka masalah dan kami akan melihatnya sesegera mungkin.

Apakah Anda ingin berkontribusi dan tidak yakin harus mulai dari mana? Ping saya di Twitter, dan saya akan membantu Anda!

Periksa file yang berkontribusi.

Lisensi

Permata tersedia sebagai open source di bawah ketentuan lisensi MIT.