[Legacy] Yowsup Documentation
Tarek edited this page Feb 13, 2015
·
1 revision
# Getting Started
## About the Library
Yowsup library is event-driven. You are provided with a set of signals that you can register callbacks to. Yowsup connection manager handles triggering of those callbacks according to data received from Whatsapp server. You are also provided with a set of methods that you can invoke inorder to send different commands to Whatsapp server.
## Invoking methods
Similar to signals, Yowsup also provides you with a list of methods that allow you to interact with Whatsapp server. To invoke a method, you first get the Methods Interface, and then invoke the associated "call" method. "call" accepts method name as first argument, and a tuple containing arguments to pass to this method. See [full list of methods](#methods)
## Authentication flow
Yowsup implements the latest authentication mechanism supported by Whatsapp 1.2 protocol called WAUTH-1. The "auth_login" method accepts phoneNumber without initial '+' or '00', and password as arguments. The method expects the real password, so any password pre-processing should be done before calling this method. You can also use Yowsup.Tools.utilities.Utilities.getPassword to generate password from a given string (usually IMEI or MAC address).
Once authentication succeeds, you must call the "ready" method to tell Yowsup to start the reader thread and begin parsing incoming messages. This is to allow you to complete any desired preparation after login, and before parsing incoming messages begins.
## Message sending flow
To send a message in Yowsup, you need the JID of the user you are sending to. The JID identifier is usually is just the phone number with country code, but without initial '+' or '00'. JID domain is "s.whatsapp.net". So an example JID would be:
123456789@s.whatsapp.net
## Message Receiving flow
When you receive a message, Yowsup emits the signal "message_received", triggering any registered listeners. One of the listeners MUST however respond by calling "message_ack", passing the jid and messageId to inform the server that the message has been received. Otherwise, the server will keep sending the same message over and over again everytime you login.
## Full list of Signals
### Authentication
auth_success(str username)
auth_fail(str username,str reason)
###Presence
presence_updated(str jid,long lastSeen)
presence_available(str jid)
presence_unavailable(str jid)
###Messages
message_received(int messageId,str jid,str content,long timestamp,bool receiptRequested)
group_messageReceived(int messageId, str jid, str author, str messageContent, long timestamp, bool wantsReceipt, str pushName):
pushName(int messageId,str jid,str author,str content,long timestamp,bool receiptRequested, str pushName)
## Full List of Methods
### Authentication
auth_login(str username,str password)
### Message Sending
message_send(str jid,str content)
typing_send(str jid)
typing_paused(str jid)
### Media
message_imageSend(str jid,str url,str name,int size,str preview)
message_videoSend(str jid,str url,str name,int size,str preview)
message_audioSend(str jid,str url,str name,int size)
message_locationSend(str jid,float latitude,float longitude,str preview)
message_vcardSend(str jid,str data,str name)
### Message and Notification Acks
message_ack(str jid,int messageId)
notification_ack(str jid,int messageId)
delivered_ack(str jid,int messageId)
visible_ack(str jid,int messageId)
subject_ack(str jid,int messageId)
### Keep Alive
ping()
pong(int pingId)
### Groups
# You should put "," after single parameters. Otherwise python will parse them as individual chars
group_getInfo(str jid,)
group_getPicture(str jid,)
group_create(str subject,)
group_addParticipants(str jid,str participants)
group_removeParticipants(str jid,str participants)
group_setPicture(str jid,str filePath)
group_end(str jid,)
group_setSubject(str jid,str subject)
group_getParticipants(str jid,)
### Presence
presence_sendAvailable()
presence_request(str jid)
presence_sendUnavailable()
presence_sendAvailableForChat()
presence_subscribe(str jid)
presence_unsubscribe(str jid)
### Contacts
contact_getProfilePicture(str jid)
picture_getIds(list jids)
### Profile
profile_getPicture()
profile_setStatus(str status)
profile_setPicture(str filePath)
### Misc
ready()
getVersion()
disconnect(str reason)
Because Yowsup reads and parses messages from Server in a separate thread, you need to make sure your application does not exit once you connect. You can achieve that by several means; for example by creating some sort of an event loop to keep your main thread running.
Yowsup has a long list of signals you can register to with callbacks. The signals are emit according to different messages received from Whatsapp. See full list of signals
Example of connecting to auth_success signal after creating a YowsupConnectionManager
def onAuthSuccess(username):
print "Logged in with %s" % s
y = YowsupConnectionManager()
signalsInterface = y.getSignalsInterface()
signalsInterface.registerListener("auth_success", onAuthSuccess)
The above example modified to actually call "auth_login" becomes:
def onAuthSuccess(username):
print "Logged in with %s" % s
# make a call to method ready to be able to receive messages
methodsInterface.call("ready")
y = YowsupConnectionManager()
signalsInterface = y.getSignalsInterface()
methodsInterface = y.getMethodsInterface()
signalsInterface.registerListener("auth_success", onAuthSuccess)
methodsInterface.call("auth_login", ("username", "password"))
You send a message to JID by calling the "message_send" method. The method accepts jid and messageContent as arguments, and returns a message Id generated by Yowsup. The message ID is useful because when you send the message, you get "sent receipt" from server, indicating the server has successfully received your message. When the message gets delivered to the specified JID, you get "delivered receipt". The message ID returned by this method will help you associate messages with their receipts. Once you get the "message delivered" receipt, you must send an ack to the server indicating reception of it. Example Code:
def onMessageSent(jid, messageId):
print "Message was sent successfully to %s" % jid
def onMessageDelivered(jid, messageId):
print "Message was delivered successfully to %s" %jid
methodsInterface.call("delivered_ack", (jid, messageId))
signalsInterface.registerListener("receipt_messageSent", onMessageSent)
signalsInterface.registerListener("receipt_messageDelivered", onMessageDelivered)
methodsInterface.call("message_send", ("identifier@s.whatsapp.net", "Hello World!"))
methodsInterface.call("message_ack", ("identifier@s.whatsapp.net", messageId)
Everytime you login, Whatsapp sends you all messages you received while you were offline
## Keep Alive Whatsapp sends a "ping" every 3 minutes of client being Idle (not sending anything) to ensure that the connection is still alive. You can enable/disable Yowsup from auto responding to these ping requests. However, if you disable it, make sure your client correctly responds to ping requests, otherwise Whatsapp will drop the connection on every ping.To Listen and respond to pings:
def onPing(pingId):
methodsInterface.call("pong", (pingId,))
signalsInterface.registerListener("ping", onPing)
To tell Yowsup to automatically respond to pings and keep connection alive
y = YowsupConnectionManager()
y.setAutoPong(True)
group_gotInfo(str jid,str owner,str subject,str subjectOwner,long subjectTimestamp,long creationTimestamp)
group_setSubjectSuccess(str jid)
group_subjectReceived(int messageId,str jid,str author,str subject,long timestamp,bool receiptRequested)
group_addParticipantsSuccess(str jid)
group_removeParticipantsSuccess(str jid)
group_createSuccess(str groupJid)
group_createFail(int errorCode)
group_endSuccess(str jid)
group_gotPicture(str jid,long pictureId,str filePath)
group_infoError(int errorCode)
group_gotParticipants(str jid,list jids)
group_setPictureSuccess(str jid)
group_setPictureError(str jid,int errorCode)
profile_setStatusSuccess(str jid,int messageId)
profile_setPictureSuccess()
profile_setPictureError(int errorCode)
receipt_messageSent(str jid,int messageId)
receipt_messageDelivered(str jid,int messageId)
receipt_visible(str jid,int messageId)
contact_gotProfilePictureId(str jid,long pictureId)
contact_typing(str jid)
contact_paused(str jid)
contact_gotProfilePicture(str jid,str filePath)
notification_contactProfilePictureUpdated(str jid,long timestamp,int messageId,long pictureId,bool receiptRequested)
notification_groupParticipantAdded(str groupJid,str jid,str author,long timestamp,int messageId,bool receiptRequested)
notification_groupParticipantRemoved(str groupJid,str jid,str author,long timestamp,int messageId,bool receiptRequested)
notification_groupPictureUpdated(str jid,str author,long timestamp,int messageId,long pictureId,bool receiptRequested)
image_received(int messageId,str jid,str preview,str url,int size,bool receiptRequested)
video_received(int messageId,str jid,str preview,str url,int size,bool receiptRequested)
audio_received(int messageId,str jid,str url,int size,bool receiptRequested)
location_received(int messageId,str jid,str name,str preview,float latitude,float longitude,bool receiptRequested)
vcard_received(int messageId,str jid,str name,str data,bool receiptRequested)
group_imageReceived(int messageId,str jid,str author,str preview,str url,int size,bool receiptRequested)
group_videoReceived(int messageId,str jid,str author,str preview,str url,int size,bool receiptRequested)
group_audioReceived(int messageId,str jid,str author,str url,int size,bool receiptRequested)
group_locationReceived(int messageId,str jid,str author,str name,str preview,float latitude,float longitude,bool receiptRequested)
group_vcardReceived(int messageId,str jid,str author,str name,str data,bool receiptRequested)
ping(int pingId)
pong()
status_dirty()
message_error(int messageId,str jid,int errorCode)
disconnected(str reason)