I recently had to figure out how to send WhatsApp messages via the WhatsApp API and figuring out the syntax and all the parts took a long time, so I'm posting what worked here.
I was sending a marketing template with two variables in the body and one button with a variable.
Step 1 - create a system user
- Find the FB business settings screen and go to the Users heading ( as of this writing, that link is https://business.facebook.com/latest/settings/business_users )
- Go to the System Users section
- Use the Add button to add your user. Give that user full admin permissions
- After the user is created, click on them to see the details, then find the Generate Token button and generate a token - this will be your Bearer token to use with API calls ( you might have to do this step after creating the app as mentioned in step 2 below, I can't remember which order I did these in )
Step 2 - create an app in WA
- Also in the business settings ( so, the same section as step 1 ), find the Accounts heading and click the Apps section
- Use the Add button to create the app. You'll need to add the 'whatsapp_business_messaging' permission
- After the app is created, click on it from the apps list to see the details. Add the system user you created to the list.
- Then, click the three dots in the top right area to open a menu and click "Open in App Dashboard"
- Move to step 3
Step 3 - add your number to the app
- In your app's App Dashboard ( the base url as of this writing is https://developers.facebook.com/apps ), make sure you are on the app you created in step 2
- In the left nav, find the WhatsApp section and open it
- Go to API Setup
- It likely gave you a test phone number. You'll need to add your real phone number. If you need a phone number to use, you can buy one via Twilio or MessageBird or something similar.
- Either via the From drop down box or the Add a Phone Number link in step 5 at the bottom of the page, click the button to add a phone number
- Once the phone number is added, you'll need to add a payment method
- Now go back to the app / App Dashboard and go to the API Setup again
- The from field should have your number ( if not, see the Gotcha's section below )
- Enter your phone number to test in the To box
- WA will have created a test "hello_world" template that it uses by default and given you sample CURL code - replace the with the Bearer token you created in step 1
- Paste that sample code into terminal and see if you get the test message
Step 4 - create your own template
- Go to the WA manager ( https://business.facebook.com/latest/whatsapp_manager/overview )
- Find the Message Templates heading in the left nav
- Either go to Manage Templates to create a new template or use the template library to use an existing template
- Note - you can only edit a template once in 24 hours and they take several hours to approve, so don't expect anything to move fast.
- See the Gotcha's section below for more things to know
Gotcha's to be aware of:
Step 3 - when adding a payment method, after you add the payment method, you have to go back into the payment method and mark it as default. Then, you have to make sure that payment method has all the business info filled out. FB / WA does not tell you any of this or give a useful error, so you just have to keep clicking around till you find this stuff.
Message templates - if you are using a marketing template, you can send one initial test message, after that, if the person does not reply, that phone number will not ever be able to get another message from you. So, if you're testing with your number, reply to that first message - just say "hi" or whatever. That will open up a 24 hour window where you can get more messages. When the window closes, just reply again.
Message template with a header - if your template has a header and you get a message about a blank param having the wrong phone number format, you'll have to remove the header from the template. I wasn't able to figure out any other way around this.
Things to note about the code below:
your-phone-number-id - you'll have to get that from the sample CURL code from Step 3.
to - that's the phone number including the country code - for me, I did no spaces and no leading plus sign
Here's the CURL code that works:
curl -i -X POST \ https://graph.facebook.com/v22.0/your-phone-number-id/messages \ -H 'Authorization: Bearer XXXXXXXXXXXXXXXXX' \ -H 'Content-Type: application/json' \ -d '{"messaging_product": "whatsapp","recipient_type": "individual","to": "xxxxxxxxxxx","type": "template","template": {"name": "template_name","language": { "code": "en_US" },"components": [ {"type": "body","parameters": [ {"type": "text","text": "Some text here for the first variable" }, {"type": "text","text": "Text for the second variable" }, ] }, {"type": "button","sub_type": "url","index": "0","parameters": [ {"type": "text","text": "text for the button variable" } ] }, ] }, }'Here's the Ruby code that works via a Ruby on Rails app:
I made a model called http_request.rb
class HttpRequest < ApplicationRecord def self.post bearer_token = 'xxxxxxxxx' url = "https://graph.facebook.com/v22.0/your-phone-number-id/messages" template_name = 'template-name' number_to = 'xxxxxxx' string_to_post = {'messaging_product': 'whatsapp','to': number_to,'type': 'template','template': {'name': template_name,'language': {'code': 'en_US' },'components': [ {'type': 'body','parameters': [ {'type': 'text','text': 'Text here' }, {'type': 'text','text': 'Text here' }, ] }, {'type': 'button','sub_type': 'url','index': '0','parameters': [ {'type': 'text','text': 'Text here' } ] }, ] } }.to_json uri = URI.parse(url) headers = {'Authorization'=>"Bearer #{bearer_token}",'Content-Type'=>'application/json' } http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true http.post(uri.path, string_to_post, headers) endend