API v2 Research

How to do this

Use MITMProxy, Fiddler2, Charles Proxy or whatever, install the CA certificate on your phone (Emulator or real Android phone) and make the phone connect through the proxy. Now use Snapchat. Quit SnapChat and take a look at them nice connection logs, every POST or GET request the application has ever made.

Notes

This is not for any malicious use, I just wanted to know what SnapChat does behind the application, and if anyone else is interested then here take a look.

The application makes a lot of requests to Crittercism, it sends off almost every movement performed in the application. Snapchat also has it's own "in house" analytics system, and that posts data every now to find out when you open the app.

I'm assuming you have already read through the GSFD, a great resource for any Snapchat API user.

Request headers

User-Agent : Snapchat/8.1.1 Beta (Android SDK built for x86; Android 19; gzip)
Accept-Language : en
Accept-Local : en_US
Content-Type : application/x-www-form-urlencoded
Host : feelinsonice-hrd.appspot.com
accept-encoding : identity
Content-Length

Response headers

Content-Type : application/json; charset=UTF-8
X-Snapchat-Notice : Snapchat Private APIs - Unauthorized use is prohibited. (Don't laugh please)
Vary : accept-encoding
Date
Server : Google Frontend
Cache-Control : no-cache, no-store or private
Alternate-Protocol : 443:quic,p=0.02
Transfer-Encoding : chunked

/ph/device

Description

Endpoint fo "DeviceSyncTask". Called when the user's notification id is different from the GCM reg ID (the device_token). This is part of the Google Cloud Messaging push notification system. (The application's SENDER_ID : 191410808405)

Request

device_token : 162 character string
username
type : android is hardcoded into the APK
timestamp
req_token
features_map : {}

Response :

No content.

/loq/register

Description

Used to create a new user.

Request

email
birthday : Format as YYYY-MM-DD
password
age : Bit stupid seeing that you provide your birth date. The application calculates this on it's own (Example : 22)
timestamp
req_token
features_map : {}

Response

email
should_send_text_to_verify_number : Boolean
snapchat_phone_number : +17864088365
auth_token
logged : Boolean

/loq/register_username

Description

Allows a user to associate a username with his / her newly created account.

Request

username : Don't be fooled, this is your email address
selected_username : The username you want to have
timestamp
req_token
features_map : {"all_updates_friends_response":true}

Response

If successful then the response should be the same as/loq/all_updates

/bq/phone_verify - Verification request

Description

Used to request phone verification

Request

countryCode : 2 letter ISO Country code
action : updatePhoneNumberWithCall or updatePhoneNumberWithMessage
phoneNumber
username
timestamp
req_token
features_map : {}

Response

action : confirm
message : We're calling your number now with a verification code.
param : The phone number with country code (Example : +33102030405)
logged : Boolean

/bq/phone_verify - Verification time

Description

Verification of the verification code

Request

action : verifyPhoneNumber
username
code : 6 digit verification code
timestamp
req_token
features_map : {}

Response

allowed_to_use_cash : NON_US_USER
message : Phone number updated!
param : The phone number with country code (Example : +33102030405)
logged : Boolean

/loq/all_updates

Description

Endpoint for "SyncAllTask". This is the greatest endpoint of them all containing most of the information, long and painful to document though...

Request

username
timestamp
req_token
features_map : {"all_updates_friends_response":true}
checksums_dict : This variable can be left empty to receive all updates, or you can provide the following to only receive... the updates. Array
- updates_checksum : 32 character string (MD5)
- friends_checksum : 32 character string (MD5)
- stories_checksum : 32 character string (MD5)
- conversations_checksum : 32 character string (MD5)

Response

background_fetch_secret_key : Base64 encoded "secret key"
conversations_response : Array
- conversation_messages : Array
  - Messages : Array
    - chat_message : Array
      - body : Array
        
        text : The message text
        
        type : text
      - chat_message_id : 36 character string containing -
      - header : Array
        
        conv_id : ToUsername~FromUsername
        
        from : username
        
        to : Array of usernames
      - id : 36 character string containing -
      - seq_num : Order of display in SnapChat (Example : 5)
      - timestamp : (Example : 1419936429914)
      - type : chat_message
    - iter_token : Strange string "{\"FromUsername\":seq_num}~{}. This follows every chat message
    - snap : Array
      - id : 19 character string with 18 digits then s or r like before
      - m : Media type
      - sn : Snap sender (Applicable when the snap is for you)
      - rp : Snap receiver (Applicable when the snap is from you)
      - st : Media state
      - sts : Time sent
      - t : Time viewable in seconds
      - timer : Time viewable in seconds as a float
      - ts : Time last interacted with
  - messaging_auth : Array
    - mac : Base64 encoded string
    - payload : 120 character string
- conversation_state : Array
  - user_chat_releases : Array
    - [Username] : Array with friend usernames as key and number of snaps received from that person as value.
  - user_sequences : Array with friend usernames as key and number of snaps received from that person as value.
  - user_snap_releases : Array
    - [Username] : Array
      - [Username] : Timestamp as value
- id : ToUsername~FromUsername
- last_chat_actions : Array
  - last_read_timestamp
  - last_reader
  - last_write_timestamp
  - last_write_type : Media type of last message (Example : text)
  - last_writer : Sender of last message
- last_interaction_ts : Timestamp of the user's last interaction
- last_snap :
  - c_id
  - id : (Example : 1r)
  - m : Media type
  - sn : Sender name (Applicable when the snap is for you)
  - rp : Recipient name (Applicable when the snap is from you)
  - st : Media state
  - sts : Time sent
  - ts : Time of last interaction
  - zipped : Boolean
- participants : Array of participants in the conversation
- pending_chats_for : Array of users who haven't opened the last message
- pending_received_snaps : Array
  - Array
    - id : Snap id
    - m : Media type
    - sn : Sender name (Applicable when the snap is for you)
    - rp : Recipient name (Applicable when the snap is for you)
    - st : Media state
    - sts : Time sent
    - t : Time viewable in seconds
    - timer : Time viewable in seconds, but a float
    - ts : Time of last interaction
conversations_response_info : Array
- is_delta : Boolean
friends_response : Array
- added_friends : Array of friends added (To be continued)
- bests : Array of best friends (To be continued)
- friends : Array
  - Array
    - add_source : ADDED_BY_USERNAME
    - can_see_custom_stories : Boolean
    - direction : OUTGOING or INCOMING
    - display : User display name
    - name : Username
    - type : Friend account privacy setting
messaging_gateway_info : Array
- gateway_auth_token : Array
  - mac : Base64 encoded string
  - payload : Base64 encoded string
- gateway_server : Server IP and port (Example : 23.251.149.90:443)
server_info : Array
- response_checksum : Array as a string
  - updates_checksum : 32 character string (MD5)
  - friends_checksum : 32 character string (MD5)
  - stories_checksum : 32 character string (MD5)
  - conversations_checksum : 32 character string (MD5)
- response_compare_result : equal or not_equal
- response_compare_results_dict : Array as a string
  - updates_checksum : equal or not_equal
  - friends_checksum : equal or not_equal
  - stories_checksum : equal or not_equal
  - conversations_checksum : equal or not_equal
- server_latency : Ping result in ms (Example : 39)
stories_response : (This part is pretty empty, haven't tried it with friends yet, gonna leave the house and find some, brb)
- friend_stories : Array (To be continued)
- friend_stories_delta : Boolean
- mature_content_text : Array
  - message : The red exclamation mark on this Story indicates that Stories posted by this user may not be suitable for sensitive viewers. Do you wish to continue? After selecting 'Yes', you will never be prompted again.
  - no_text : No
  - yes_text : Yes
  - title : Content Warning
- my_group_stories : Array (To be continued)
- my_stories : Array (To be continued)
updates_response : Array
- added_friends_timestamp : I suppose it's the last time you added a friend. I don't have any I wouldn't know.
- allowed_to_use_cash : NON_US_USER(Need someone from the US to get us Snapcash details)
- auth_token
- birthday : Kind reminder of your birthday (YYYY-MM-DD)
- blocked_from_using_our_story : Boolean
- can_view_mature_content : Boolean
- cash_customer_id : Username
- cash_provider : SQUARE
- client_properties : Array
  - snapcash_new_tos_accepted : Boolean
  - snapcash_tos_v2_accepted : Boolean
- contacts_resync_request : (Example : 1)
- country_code : ISO 2 letter country code
- current_timestamp : A current UNIX timestamp. Thanks for that.
- device_token : Empty
- email
- enable_video_transcoding_android : Boolean
- feature_settings : Array
  - front_facing_flash : Boolean
  - power_save_mode : Boolean
  - replay_snaps : Boolean
  - smart_filters : Boolean
  - special_text : Boolean
  - swipe_cash_mode : Boolean
  - visual_filters : Boolean
- image_caption : Boolean
- is_cash_active : Boolean
- logged : Boolean
- mobile : Phone number with country code (Example : +33102030405)
- mobile_verification_key : Base64 encoded string with 4 digit code and username (Example : 1234:Username)
- notification_sound_setting : ON or OFF
- number_of_best_friends
- received : Number of received snaps
- recents : Array containing usernames of recently interacted friends
- requests : Array (To be continued)
- score : Your snapchat score
- searchable_by_phone_number : Boolean
- sent : Number of sent snaps
- should_call_to_verify_number : Boolean
- should_send_text_to_verify_number : Boolean
- snap_p : Account privacy setting
- snapchat_phone_number : (Example : +17864088362)
- store_privacy : Story privacy setting
- study_settings : Array
  - DELTA_RESPONSE : Array as a string
    - experimentId : 1
    - CONVERSATIONS_DELTA : on or off
    - FRIENDS_STORY_DELTA : on or off
  - USE_VIDEO_STABILIZATION : Array as a string
    - experimentId : 0
    - option : on or off
- user_id : 36 character string containing -
- username

/ph/upload

Description

Endpoint for "UploadMediaTask". Used to upload media to the server

Request

data : Encrypted image data
media_id : Username in capitals and a random media ID
type : Media type
username
req_token
timestamp
features_map : {}

Response

No content.

/loq/send

Description

Used to send media to users

Request

time : Snap countdown timer (Float)
recipients : Array of usernames
media_id : The media id used when uploading the media
zipped : (Example : 0)
username
req_token
timestamp
features_map : {}

Response

snap_response : Array
- snaps : Array
  - [ToUsername] : Array
    - id : The snap's ID
    - timestamp
- success : Boolean

/loq/conversations

Description

Endpoint for "LoadFeedPageTask". Used to check for new conversations.

Request

checksum : 32 character string (MD5)
offset : [TimestampOfLastMessage]~[ToUsername]~[FromUsername] - Optional
username
req_token
timestamp
features_map : {"all_updates_friends_response":true}

Response

server_info : Array
- response_checksum : 32 character string (MD5)
- response_compare_result : equal or not_equal
- server_latency : Ping time in ms (Example : 39)

/bq/chat_typing

Description

Informs the server and recipient that the user is typing

Request

recipient_usernames : Array of usernames
username
req_token
timestamp
features_map : {}

Response

No content.

/ph/find_friends

Description

Used to find users by phone number

Request

countryCode : ISO 2 letter country code
numbers : Array with display name as key and phone number as value (The official client sends off all numbers at once. Maybe there is no limit ?)
username
req_token
timestamp

Response

logged : Boolean
results : Array
- Array
  - display : Name provided as display name in the request
  - name : Username
  - type : User's privacy setting

/ph/settings

Description

Used to change various settings

Request

action : updatePrivacy or updateEmail or updateStoryPrivacy or updateSearchableByPhoneNumber or updateCanViewMatureContent
privacySetting : Applicable for action = updatePrivacy or updateStoryPrivacy
searchable : 0 or 1 - Applicable for action = updateSearchableByPhoneNumber
email : Applicable for action = updateEmail
canViewMatureContent : Boolean - Applicable for action = updateCanViewMatureContent
username
req_token
timestamp
features_map : {}

Response

logged : Boolean
message : User friendly success / error message
param : The new updated parameter

/bq/set_num_best_friends

Description

Sets the number of best friends to display for your username

Request

num_best_friends : Number from 3 to 7
username
req_token
timestamp
features_map : {}

Response

best_friends : Array of best friend usernames

/bq/update_feature_settings

Description

Used to change extra feature settings

Request

settings : Array
- front_facing_flash : Boolean
- replay_snaps : Boolean
- smart_filters : Boolean
- visual_filters : Boolean
username
req_token
timestamp
features_map : {}

Response

No content.

/ph/logout

Description

Used to push updates and end the user's session

Request

added_friends_timestamp : Time of the last added friend
events : You can post a whole load of events here. But I don't feel like documenting that today.
json : Array of snap updates
username
req_token
timestamp

Response

No content.

/loq/login

Description

Authenticates the user with the server

Request

username
password
access_token : a 675 character string containing . _ -
req_token
timestamp
features_map : {"all_updates_friends_response":true}

Response

Error

logged : Boolean
message : User friendly error message
status : Integer

Success

If successful then the response should be the same as/loq/all_updates

/bq/bests

Description

Gets the best friends and scores of a selection of friends

Request

friend_usernames : Array of friend usernames
username
req_token
timestamp
features_map : {}

Response

Array
- [FriendUsername] : Array
  - best_friends : Array of up to 3 of the user's best friends
  - score : User's score

/loq/conversation_auth_token

Description

Normally called just after adding a user a friend, provides encryptions keys for encrypting / decrypting conversation messages

Request

conversation_id : [YourUsername]~[OtherUsername]
username
req_token
timestamp

Response

messaging_auth
- mac : Base64 encoded string
- payload : 112 character string

/bq/friend

Description

Used to add / remove / block / unblock / change display name for a friend

Request

action : add or remove or block or unblock or delete or display
friend : Friend's username
display : New display name - Applicable only if action = display
username
req_token
timestamp
features_map : {}

Response

logged : Boolean
message : User friendly error / success message
object : Array
- add_source : How the friend was added
- can_see_custom_stories : Boolean
- direction : INCOMING or OUTGOING
- display : User's display name
- name : Friend's username
- type : Friend account privacy setting

/loq/friend_search

Description

Used to search shared stories

Request

query : The user you are looking for
username
req_token
timestamp
features_map : {}

Response

result : Array

/bq/user_exists

Description

Used to find user's that aren't in your friend list

Request

request_username : The username you are looking for
username
req_token
timestamp

Response

exists : Boolean
logged : Boolean (Optional)
throttled : Boolean (Optional)

/loq/friend_hide

#### Description Used when hiding shared stories. The kind that are forced into your story list. When you hide a shared story the application also deletes the friend by firing off a request to /bq/friend

Request

friend : Friend's username
hide : Boolean
username
req_token
timestamp

Response

can_see_custom_stories : Boolean
direction : INCOMING or OUTGOING
display : Friend's display name
dont_decay_thumbnail : Boolean
expiration : The time when the shared story should dissapear from your client
has_custom_description : Boolean
is_shared_story : Boolean
name : Friend's username
shared_story_id : Should be the same as name
type : Friend's privacy setting
venue : Location of shared story event

/shared/description

Description

Called for every shared story in the story view to provide a description to the user

Request

shared_id : The shared story's id
username
req_token
timestamp
features_map : {}

Response

Haven't seen a shared story with a description yet.

/bq/update_stories

Description

Endpoint for "UpdateStoriesTask". Whenever a story is viewed by the user the application notifies the server of the view, the time of viewing and the amount of screenshots taken. This endpoint can accept a whole load of different viewed snaps at once.

Request

friend_stories : Array
- Array
  - id : Story snap id
  - screenshot-count : Integer
  - timestamp : Time viewed
username
req_token
timestamp
features_map : {}

Response

No content.

/bq/retry_post_story

Description

This is used by default on the Android application when posting a new story, even though it was originally meant to be used in case of failure, it's an all in one endpoint for uploading and posting the story.

Request

my_story : Boolean
time : Number of seconds to display the snap. Float
group_ids : Array (Don't know how to get in a group yet...)
data : The snap data
media_id : [Username]~[Random 36 character string containing -]
story_timestamp : No idea, I had 245388641
zipped : 0 or 1
caption_text_display : The title to be displayed when viewing a list of your snaps.
client_id : Same as media_id for me
type : Type of media (0 for images - 1 for videos)
username
req_token
timestamp

Response

json : Array
- story : Array
  - caption_text_display
  - client_id
  - id : [Username]~[Timestamp]
  - mature_content : Boolean
  - media_id : 16 digit Media ID
  - media_iv : Base64 encoded encryption IV for the snap data
  - media_key : Base64 encoded decryption key for the snap data
  - media_type : 0 for images - 1 for videos
  - media_url : A URL to fetch the story data, generally https://feelinsonice-hrd.appspot.com/bq/story_blob?story_id=[media_id]
  - thumbnail_iv : Base64 encoded encryption IV for the thumbnail image
  - thumbnail_url : A URL to fetch the thumbnail image, generally https://feelinsonice-hrd.appspot.com/bq/story_thumbnail?story_id=[media_id]
  - time : Number of seconds to display snap. Float
  - time_left : Time left before expiration of the story in ms
  - timestamp : Time posted in ms
  - username : Username of the user who posted the story
  - zipped : Boolean

/cash/check_recipient_eligible

Description

Used to check if a recipient is eligible to use the Snapcash service. It is called in the application when viewing a conversation with a friend.

Request

recipient : Friend's username
username
req_token
timestamp

Response

status : The Snapcash status for the specified user. (Example : SERVICE_NOT_AVAILABLE_TO_RECIPIENT)

/bq/delete_story

Description

Allows a user to delete a snap from their story

#### Request

story_id : [Username]~[Timestamp]
username
req_token
timestamp

Response

No content.

/log/conversation_post_messages

Description

Endpoint for "PostChatsTask". Used when sending a message in a conversation

Request

Array
- known_chat_sequence_numbers : Array
  - [Username] : Integer (No idea)
- known_received_snaps_s : Array
  - [Username] : Timestamp of last received snap from that person
- release_type : release or delete
- timestamp : 0
- header : Array
  - auth : Array
    - mac
    - payload
  - to : Array of usernames
  - conv_id : [Username]~[Username]
  - from : Username
  - conn_seq_num : Integer
- retried : Boolean
- id : 36 character string containing -
- type : message_release
username
req_token
timestamp
features_map : {}

Response

conversations : Array
- conversation_messages : Array
  - messages : Array
    - Array
      - chat_message : Array
        
        body : Array
        
        text : Message text - Applicable if type = text
        
        media : Array - Applicable if type = media
        
        iv : Base64 encoded encryption IV
        
        key : Base64 encoded decryption key
        
        media_id : 36 character string containing -
        
        type : text or media
        
        chat_message_id : 36 character string containing -. Same as media_id if type = media
        
        header : Array
        
        conv_id : [Username]~[Username]
        
        from : Username
        
        to : Array of usernames
        
        saved_state : Optional array
        
        [Username] : Array
        
        saved : Boolean
        
        version : Integer
        
        id : 36 character string containing -
        
        seq_num : Integer
        
        timestamp
        
        type : chat_message
      - iter_token : Array as string appended with ~{}
        
        [Username] : [seq_num]
  - messaging_auth : Array
    - mac : Base64 encoded string
    - payload
- conversation_state : Array
  - user_chat_releases : Array
    - [Username] : Array with friend usernames as key and number of snaps received from that person as value.
  - user_sequences : Array with friend usernames as key and number of snaps received from that person as value.
  - user_snap_releases : Array
    - [Username] : Array
      - [Username] : Timestamp as value
- id : ToUsername~FromUsername
- last_chat_actions : Array
  - last_read_timestamp
  - last_reader
  - last_write_timestamp
  - last_write_type : Media type of last message (Example : text)
  - last_writer : Sender of last message
- last_interaction_ts : Timestamp of the user's last interaction
- last_snap :
  - c_id
  - id : (Example : 1r)
  - m : Media type
  - sn : Sender name (Applicable when the snap is for you)
  - rp : Recipient name (Applicable when the snap is from you)
  - st : Media state
  - sts : Time sent
  - ts : Time of last interaction
  - zipped : Boolean

/loq/local_story - Incomplete

Description

Request

username
latitude
longitude

Response

createdFriendStories : Array
createdFriends : Array
location

/log/update_user - Incomplete

Description

Request

username
seenToolTips : Array
clientProperties : Array

Response

/bq/get_captcha - Incomplete

Description

Endpoint for "GetCaptchaTask"

Request

username

Response

/bq/solve_captcha - Incomplete

Description

Endpoint for "SolveCaptchaTask"

Request

captcha_id
captcha_solution
username

/loq/gae_server_list - Incomplete

Description

Endpoint for the "GetEndpointSetTask". Something to do with pinging the endpoint server