ruby_whatsapp_sdk

Ruby WhatsApp SDK

O SDK fornece um conjunto de operações e classes para usar a API do WhatsApp. Envie adesivos, mensagens, áudio, vídeos, locais, reagem e resposta a mensagens ou apenas peça os números de telefone através desta biblioteca em algumas etapas!

Demonstração

Messageapidemo.mov

Verifique o repositório de exemplos de exemplos de exemplo do Ruby on Rails que usa esta biblioteca para enviar mensagens.

Instalação

Adicione esta linha ao GemFile do seu aplicativo:

 gem 'whatsapp_sdk'

E depois execute:

 $ bundle

Ou instale você mesmo como:

 $ gem install whatsapp_sdk

Início rápido

Existem três recursos primários, Messages , Media e PhoneNumbers . Messages permitem que os usuários enviem qualquer mensagem (texto, áudio, localização, vídeo, imagem etc.). Media permite que os usuários gerenciem a mídia e Phone Numbers permitam que os clientes consultem os números de telefone associados.

Para usar Messages , Media ou PhoneNumbers , você precisa inicializar o Client que contém informações de autenticação. Existem duas maneiras de fazer isso.

Opção 1) Use um inicializador

 # 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

Notas:

• Opcionalmente, você pode especificar a versão da API desejada a ser usada (padrão para a versão mais recente, se omitida). A versão da API disponível pode ser encontrada aqui.
• Você pode anexar um logger. Mais detalhes sobre as opções de Logger de Faraday estão aqui.

Opção 2) Crie uma instância 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 ) 

Configure um meta aplicativo

1) Crie um aplicativo de meta de negócios

2) Adicione o WhatsApp ao seu aplicativo

3) Adicione um número de telefone à sua conta

Tente enviar uma mensagem para o seu telefone na interface do usuário.

4) Copie o access_token, o sender_id, o Business_id e o destinatário_number

5) Use a jóia para interagir com o WhatsApp

Exemplo:

1. Instale o gem executando gem install whatsapp_sdk no gem.
2. Abra o terminal IRB executando irb
3. require "whatsapp_sdk"
4. Configure o ACCESS_TOKEN , o SENDER_ID , o BUSINESS_ID e o RECIPIENT_NUMBER em variáveis.

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

5. Configure o cliente executando

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

6. Experimente a API de números de telefone ou API de mensagens

API de números de telefone

 registered_number = client . phone_numbers . registered_number ( SENDER_ID )

Mensagens API

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

Verifique o arquivo exemplo.rb para obter mais exemplos.

Espreita furtiva

 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 ) 

APIs

Modelos

 # 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 do perfil de negócios

 # 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 de números de telefone

 # 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 da mídia

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

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

Exemplo do componente

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

Como alternativa, você pode passar por um json simples assim:

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

Enviar mensagens interativas Visite a documentação oficial da API

Listar o exemplo da mensagem

 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
)

Como alternativa, você pode passar por um json simples assim:

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

Exemplo do botão Responder

 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
)

Alternativa, você pode passar por um json simples assim:

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

Erros

Se a API retornar um erro, uma exceção WhatsappSdk::Api::Responses::HttpResponseError será aumentada. O objeto contém informações retornadas pela API da nuvem. Para obter mais informações sobre o potencial erro, verifique a documentação oficial.

Exemplos

Visite o arquivo de exemplo com exemplos para ligar para a API em um único arquivo.

Whatsapp Cloud API

• Veja a documentação oficial da API do WhatsApp Cloud.
• Para preços, consulte a documentação oficial. A partir de hoje, as ofertas do WhatsApp têm 1000 conversas gratuitas por mês.

Solução de problemas

Se você tentar enviar uma mensagem de texto diretamente sem um modelo de mensagem criado e aprovado no seu painel de meta controle, não poderá iniciar um bate -papo com outras pessoas. Mas se você receber uma mensagem antes, é possível enviar uma mensagem.

Se a resposta da API ainda for success , mas a mensagem não será entregue:

• Verifique se o dispositivo em que você está enviando a mensagem está usando uma versão do WhatsApp suportada. Verifique a documentação. Tente também responder uma mensagem ao número que você está registrado no seu WhatsApp.
• Verifique se o seu meta aplicativo usa uma versão da API maior ou igual a v.14 .
• Verifique se o painel no painel do Facebook não exibe nenhum erro.

Nota: Às vezes, as mensagens são atrasadas; Veja meta documentação.

Desenvolvimento

Depois de verificar o repositório, execute bin/setup para instalar dependências. Em seguida, execute rake test para executar os testes.

Execute 'Instalação de rake Exec de pacote' para instalar esta gema na sua máquina local. Para lançar uma nova versão, atualize o número da versão no version.rb e, em seguida, execute bundle exec rake release , que criará uma tag git para a versão, push git cometa e tags e pressionará o arquivo .gem para rubygems.org.

Execute todos os testes

• Testes de unidade: Executar rake test
• Sorbet TypeCheck: Run srb tc
• Linters: bundle exec rubocop

Para atualizar a versão da API em nuvem, atualize a versão em lib/whatsapp_sdk/api/api_configuration.rb . Verifique o ChanGelog da API Cloud para obter os API UDPATES.

Contribuindo

Relatórios de bugs e solicitações de tração são bem-vindos no github em https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk Este projeto deve ser um espaço seguro e acolhedor para a colaboração, e os contribuidores devem aderir ao código de conduta do contribuinte.

Se você deseja que um recurso seja implementado na gema, abra um problema e daremos uma olhada o mais rápido possível.

Você quer contribuir e não tem certeza por onde começar? Me ping no Twitter, e eu vou te ajudar!

Verifique o arquivo contribuinte.

Licença

A GEM está disponível como código aberto nos termos da licença do MIT.