ruby_whatsapp_sdk

Ruby WhatsApp SDK

SDK提供了一組操作和類來使用WhatsApp API。發送貼紙，消息，音頻，視頻，位置，反應和回复消息，或者只需通過幾個步驟通過此庫詢問電話號碼！

演示

Messageapidemo.mov

檢查Rails上的Ruby WhatsApp示例存儲庫，該存儲庫使用此庫發送消息。

安裝

將此行添加到您的應用程序的gemfile：

 gem 'whatsapp_sdk'

然後執行：

 $ bundle

或自行安裝：

 $ gem install whatsapp_sdk

快速開始

有三個主要資源， Messages ， Media和PhoneNumbers 。 Messages允許用戶發送任何消息（文本，音頻，位置，視頻，圖像等）。 Media允許用戶管理媒體， Phone Numbers使客戶能夠查詢關聯的電話號碼。

要使用Messages ， Media或PhoneNumbers ，您需要初始化包含驗證信息的Client 。有兩種方法可以做到。

選項1）使用初始器

 # 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

筆記：

• 可選地，您可以指定要使用的所需API版本（默認為最新版本（如果省略））。可用的API版本可以在此處找到。
• 您可以連接記錄器。有關Faraday Logger選項的更多詳細信息在這裡。

選項2）創建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 ) 

設置一個元應用

1）創建一個元業務應用程序

2）將WhatsApp添加到您的應用程序

3）向您的帳戶添加電話號碼

嘗試在UI中向您的手機發送消息。

4）複製access_token，sender_id，business_id和contoct_number

5）使用寶石與WhatsApp互動

例子：

1. 通過運行gem install whatsapp_sdk寶石。
2. 通過運行irb打開IRB終端
3. require "whatsapp_sdk"
4. 在變量中設置ACCESS_TOKEN ， SENDER_ID ， BUSINESS_ID和RECIPIENT_NUMBER 。

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

5. 通過運行配置客戶端

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

6. 嘗試電話號碼API或消息API

電話號碼API

 registered_number = client . phone_numbers . registered_number ( SENDER_ID )

消息API

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

檢查示例.RB文件以獲取更多示例。

偷看

 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 ) 

蜜蜂

模板

 # 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

 # 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

 # 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

 # 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 )

消息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)

組件的示例

 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 : [ ... ]
)

另外，您可以通過這樣的簡單JSON：

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

發送交互式消息訪問官方API文檔

列表消息的示例

 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
)

另外，您可以通過這樣的簡單JSON：

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

回复按鈕的示例

 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
)

替代方案，您可以通過這樣的簡單JSON：

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

錯誤

如果API返回錯誤，則會提高異常WhatsappSdk::Api::Responses::HttpResponseError 。該對象包含雲API返回的信息。有關潛在錯誤的更多信息，請檢查正式文檔。

例子

訪問帶有示例的示例文件，以在單個文件中調用API。

WhatsApp Cloud API

• 請參閱WhatsApp Cloud API的官方文檔。
• 有關定價，請參閱官方文件。截至今天，WhatsApp優惠每月免費提供1000次對話。

故障排除

如果您嘗試直接發送短信而沒有在元控制面板中創建和批准的消息模板，則無法與其他人聊天。但是，如果您之前收到消息，則可以發送消息。

如果API響應仍然是success ，但是該消息未傳遞：

• 確保您發送消息的設備使用支持的WhatsApp版本。檢查文檔。還嘗試將消息回复您在WhatsApp上註冊的號碼。
• 確保您的Meta應用使用大於或等於v.14 API版本。
• 確保Facebook儀表板中的面板不會顯示任何錯誤。

注意：有時消息會延遲；請參閱元文檔。

發展

檢查回購後，運行bin/setup以安裝依賴關係。然後，運行rake test以運行測試。

運行“ Bundle Exec Rake rake install”以將此寶石安裝到本地計算機上。要發布新版本，請在version.rb中更新版本號，然後運行bundle exec rake release Release ，該版本將為版本創建一個git標籤，推送git consits and tags，然後將.gem文件推到rubygems.org。

運行所有測試

• 單位測試：運行rake test
• 冰糕Typecheck：運行srb tc
• Linters： bundle exec rubocop

要更新雲API版本，更新了lib/whatsapp_sdk/api/api_configuration.rb中的版本。檢查雲API更換件中的API udpates。

貢獻

歡迎在https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk上的GitHub上的錯誤報告和拉動請求，該項目旨在是一個安全，熱情的協作空間，預計貢獻者有望遵守貢獻者的行為代碼。

如果您希望在GEM中實現一個功能，請打開一個問題，我們將盡快查看。

您想貢獻並不確定從哪裡開始嗎？在Twitter上ping我，我會幫助您！

檢查貢獻文件。

執照

根據MIT許可證的條款，該寶石可作為開源。