[Legacy] Yowsup Documentation

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

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.

Connecting to signals

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)

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

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

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

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!"))    

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

methodsInterface.call("message_ack", ("identifier@s.whatsapp.net", messageId)

Offline Messages

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)

Signals and Methods

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

Groups

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

profile_setStatusSuccess(str jid,int messageId)
profile_setPictureSuccess()
profile_setPictureError(int errorCode)

Receipts

receipt_messageSent(str jid,int messageId)
receipt_messageDelivered(str jid,int messageId)
receipt_visible(str jid,int messageId)

Contacts

contact_gotProfilePictureId(str jid,long pictureId)
contact_typing(str jid)
contact_paused(str jid)
contact_gotProfilePicture(str jid,str filePath)

Notifications

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)

Media

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)

Keep Alive

ping(int pingId)
pong()

Misc:

status_dirty()
message_error(int messageId,str jid,int errorCode)
disconnected(str reason)

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