heyooh
Unofficial javascript wrapper to WhatsApp Cloud API. Its the javascript port for heyoo
Features supported
- Sending messages
- Sending Media (images, audio, video and ducuments)
- Sending location
- Sending interactive buttons
- Sending template messages
Getting started
To get started with heyooh, you have to firstly install the libary either directly or using npm.
Installation directly
Use git to clone or you can also manually download the project repository just as shown below;
$ git clone https://github.com/JS-Hub-ZW/heyooh
$ cd heyooh
Installing from npm
# For Windows, Linux & Mac
npm install heyooh
Setting up
To get started using this package, you will need TOKEN and TEST WHATSAPP NUMBER which you can get by from Facebook Developer Portal
Here are steps to follow for you to get started
- Go to your apps
- create an app
- Select Bussiness >> Bussiness
- It will prompt you to enter basic app informations
- It will ask you to add products to your app a. Add WhatsApp Messenger
- Right there you will see a your TOKEN and TEST WHATSAPP NUMBER and its phone_number_id
- Lastly verify the number you will be using for testing on the To field.
Once you're follow the above procedures, now you're ready to start hacking with the Wrapper.
Authentication
Here how you authenticate your application, you need to specofy two things the TOKEN
and phone_number_id
of your test number
import {WhatsApp} from 'heyooh'
let messenger = new WhatsApp('TOKEN', phone_number_id='104xxxxxx')
Once you have authenticated your app, now you can start using the above mentioned feature as shown above;
Sending Messanges
Here how to send messages;
messenger.send_message('Your message ', 'Mobile eg: 255757xxxxx')
Example
Here an example
messenger.send_message('Hi there just testiing', '255757902132')
Sending Images
When sending media(image, video, audio, gif and document ), you can either specify a link containing the media or specify object id, you can do this using the same method.
By default all media methods assume you're sending link containing media but you can change this by specifying the link=False
.
Here an example;
messenger.send_image(
image="https://i.imgur.com/Fh7XVYY.jpeg",
recipient_id="255757xxxxxx",
)
Sending Video
Here an example;
messenger.send_video(
video="https://www.youtube.com/watch?v=K4TOrB7at0Y",
recipient_id="255757xxxxxx",
)
Sending Audio
Here an example;
messenger.send_audio(
audio="https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
recipient_id="255757xxxxxx",
)
Sending Document
Here an example;
messenger.send_document(
document="http://www.africau.edu/images/default/sample.pdf",
recipient_id="255757xxxxxx",
)
Sending Location
Here an example;
messenger.send_location(
lat=1.29,
long=103.85,
name="Singapore",
address="Singapore",
recipient_id="255757xxxxxx",
)
Sending Interactive buttons
Here an example;
messenger.send_button(
recipient_id="255757xxxxxx",
button={
"header": "Header Testing",
"body": "Body Testing",
"footer": "Footer Testing",
"action": {
"button": "Button Testing",
"sections": [
{
"title": "iBank",
"rows": [
{"id": "row 1", "title": "Send Money", "description": ""},
{
"id": "row 2",
"title": "Withdraw money",
"description": "",
},
],
}
],
},
},
)
Sending a Template Messages
Here how to send a pre-approved template message;
messenger.send_template("hello_world", "255757xxxxxx")
Sending a Template Messages with Components
You can now specify components like this
let components = [
// Your components here
]
messenger.send_template("hello_world", "255757xxxxxx", components)
For moreabout components: https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates
Webhook
Webhooks are useful incase you're wondering how to respond to incoming message send by user, but I have created a starter webhook which you can then customize it according to your own plans.
To learn more about webhook and how to configure in your Facebook developer dashboard please have a look here.
Notification Payload Structure
This is the structure of the notifications that you will recieve from Whatsapp when a certain event is triggered
Example Notification Payload | Nested Structure of the Payload |
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE-NUMBER",
"phone_number_id": "PHONE-NUMBER-ID"
},
# Additional arrays and objects
"contacts": [{...}]
"errors": [{...}]
"messages": [{...}]
"statuses": [{...}]
},
"field": "messages"
}]
}]
} |
Recieving notifications
To receive notifications such as customer messages, alerts and other callbacks from WhatsApp
import Server from './classes/server'
import 'dotenv/config'
let notificationServer = new Server(
process.env.LISTEN_PORT,
process.env.VERIFY_TOKEN
)
let app = notificationsServer.start(async (rawData ,processedPayload) => {
// Do your stuff here
let messages = processedPayload.get_messages()
let metadata = processedPayload.get_contacts()
let contacts = processedPayload.get_contacts()
let status = processedPayload.get_statuses()
// Do other stuff here
})
rawData
-> This is raw data straight from WhatsApp
processedPayload
-> This is an object of ProcessPayload
it gives access to the raw_data plus helper methods
Note: Beginners should work more with processed since it saves you time and minimizes errors
Tip: You can refactor it to look more presentable
import handleNotifications from 'path/to/file'
let app = notificationServer.start(handleNotifications)
Getting media links
To retrive actual media link
let message = processedPayload.get_messages()[0]
let mediaData = await messenger.get_media(message.image.id)
NOTE: The URL you get is only available for a 5 minutes, so you may need to download it and store it somewhere, or use it as quick as possible
For more info check Notification Payload refernce and Notification Payload Examples
Issues
If you will face any issue with the usage of this package please raise one so as we can quickly fix it as soon as possible;
Contributing
This is an opensource project under MIT License
so any one is welcome to contribute from typo, to source code to documentation, JUST FORK IT
.