You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/API.md
+31-18Lines changed: 31 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,16 +1,16 @@
1
1
# API
2
2
3
-
All non-image get requests are made to \<ip>:\<port>/requests. Requests for attachments are made to /attachments, and requests for profile images are made to /profile.
4
-
5
-
All post requests are directed to /send. In the latest version, this is the only way to send texts and/or attachments.
3
+
All plain text GET requests must be made to \<ip>:\<port>/requests (e.g. 192.168.0.127:8741/requests). Requests for binary data (whether it be pictures from the camera roll, profile pictures, or attachments) must be sent to /data. All post requests must be directed to /send.
6
4
7
5
All request parameters require a value, but only some of the values are consequential. However, the app will not interpret a parameter as a parameter unless it has an accompanying value -- For example, to retrieve the list of conversations, one must make a request to /requests with a parameter of 'chat', but 'GET /requests?chat' will return nothing. Something like 'GET /requests?chat=0' will return the correct information.
8
6
9
7
# `/requests` requests:
10
8
11
9
All requests to `/requests` return JSON information.
12
10
13
-
## `person`, `num`, `offset`, `read`
11
+
The below sections detail the query key/value pairs that you can combine to get the information you need from the API.
12
+
13
+
## `person`, `num`, `offset`, `read`, `from`
14
14
15
15
Retrieves the most recent \$num messages to or from \$person, offset by \$offset.
16
16
@@ -23,9 +23,11 @@ $\qquad$ As of version 0.5.4, you may also send multiple addresses to this param
23
23
24
24
- read: Parameter is not necessary, but value is consequential. The value of this parameter must be a string, either `true` or `false`. If it is `true`, or the parameter is not included but the 'mark conversation as read when viewed on web interface' option is checked in the app's settings, the conversation whose messages are being requested will be marked as read on the host device.
25
25
26
+
- from: Parameter is not necessary, but value is consequential. The value of this parameter must be an int, either 0, 1, or 2. If you pass 0 for this key, this request will grab texts both to and from you in this conversation. If you pass 1 in for this key, it will grab only texts that are from you, and if you pass in 2, it will only grab texts that are to you.
Requests to this url are all sent using `POST`, are what are used to send texts and attachments. There are four arguments that can be sent to this, and it accepts multiple files as well. For the text to actually send, you must include the chat, and then either at least 1 file, or something that is more than 0 characters for one of the other parameters.
122
+
Requests to this url are all sent using `POST`, as opposed to `GET`, as multipart/form-data forms (as opposed to application/x-www-form-urlencoded). In practice, it's generally safe to not encode anything in requests to this url, but only percent encodings (e.g. using `%20` for spaces and `%2B` for plus signs) will be accepted and parsed correctly. For example, replacing spaces with plus signs (as is specified in [RFC1738](https://www.ietf.org/rfc/rfc1738.txt) will cause the string to be used raw, and none of the plus signs will be replaced with spaces.
123
+
124
+
There are five key/value pairs that can be sent to this URL, and it accepts multiple files as well. For the text to actually send, you must include the chat, and then either at least 1 file, or something that is more than 0 characters for one of the other parameters.
121
125
122
126
As with all other requests (besides to the gatekeeper), you must authenticate before sending any requests to this url, or else nothing will happen.
123
127
124
128
## Arguments
125
129
126
130
## text
127
131
128
-
This argument contains the body of the text you want to send. This parameter is not necessary for every request
132
+
The value for this key simply contains the body of the text you want to send.
129
133
130
134
## subject
131
135
132
-
This argument contains the subject of the text that you want to send. For it to actually be included with the text, it must be at least 1 character long (not just ""), and you must have the `Enable subject line in web interface (and API)` option toggled on in your app's settings. If it is 0-length or the subject setting is toggled off, the text will still be sent but it won't have a subject.
136
+
The value for this key contains the subject of the text that you want to send. For it to actually be included with the text, it must be at least 1 character long (not just ""); if it is 0-length or you simply don't include this key/value pair, the text will still be sent but it won't have a subject.
133
137
134
138
## chat
135
139
136
-
This argument contains the chat_identifier of the recipient, specified as in the `person` parameter above. Before 0.1.0+debug77, these could only be an address for an existing conversation, but with version 0.1.0+debug77 of SMServer (and 0.1.0-85+debug of libsmserver), you can post requests for new conversations; new conversations do not yet support attachments, though.
140
+
The value for this key contains the chat_identifier of the recipient, specified as in the `person` parameter above. Before 0.1.0+debug77, these could only be an address for an existing conversation, but with version 0.1.0+debug77 of SMServer (and 0.1.0-85+debug of libsmserver), you can post requests for new conversations; new conversations do not yet support attachments, though.
137
141
138
-
This parameter is necessary for every request, or else the app won't know who to send the text to. Also, plus signs should not be replaced with an escape character for these requests; they should stay plus signs.
142
+
This parameter is necessary for every request, or else the app won't know who to send the text to.
139
143
140
144
## photos
141
145
142
-
This argument will contain a list of the path of the photos (from the camera roll) that you want to send with this text, but separated by colons and without the `/var/mobile/Media/` section of their path. For example, if you wanted to send three photos with this text, this parameter would look something like `DCIM/100APPLE/IMG_0001.JPG:DCIM/100APPLE/IMG_0002.JPG:DCIM/100APPLE/IMG_0003.JPG`.
146
+
The value for this key will contain a list of the path of the photos (from the camera roll) that you want to send with this text, but deliminted by colons and without the `/var/mobile/Media/` section of their path. For example, if you wanted to send three photos with this text, this parameter would look something like `DCIM/100APPLE/IMG_0001.JPG:DCIM/100APPLE/IMG_0002.JPG:DCIM/100APPLE/IMG_0003.JPG`.
143
147
144
148
## files
145
149
146
-
These need to be sent with the key 'attachments'. Other than that, just send them as normal. It does support sending multiple attachments, but (obviously), the more attachments you send, the longer it'll take, and the higher likelihood it'll fail along the way.
150
+
These need to be sent with the key 'attachments'. Other than that, just send them as normal. It does support sending multiple attachments, but (obviously), the more attachments you send, the longer it'll take, and the higher likelihood it'll fail along the way.
147
151
148
152
## Example requests
149
153
150
-
### Python3—
154
+
### Python3
151
155
152
156
Sending a text with a subject and no attachments:
153
157
```python
154
158
from requests import post
155
159
156
-
# It's safest to explicitly replace spaces with `%20`, since (last time I tested) python replaced
157
-
# all spaces with plus signs, which are not filtered out.
160
+
# It's safest to explicitly encode spaces as `%20`, since python replaces all spaces with plus signs,
161
+
# which are not filtered out. If your scripting language does not replace spaces with plus signs,
I've read that the value for `attachments` in `files_values` could be a list of tuples (a list of variables like `file` in the example above), but doing that has caused python to fail to post the request every time I've tried it, so I would recommend just iterating over each attachment and sending them individually.
179
185
180
186
Sending a text with a subject and a photo from the camera roll:
To be able to send a text with a subject, the `subject` variable in `vals` must not be empty, and you must have the option `Enable subject functionality` toggled on in the app
194
-
195
-
I've read that the value for `attachments` in `files_values` could be a list of tuples (a list of variables like `file`), but doing that has caused python to fail every time I've tried it, so I would recommend just iterating over each attachment and sending them individually.
199
+
### Curl
200
+
Sending a text with a body, subject, and attachments with curl
/// Send the code that you want it to run, basically
47
-
[controller sendQueryWithReply:NO query: ^{
48
-
/// Do your IMCore/ChatKit stuff here
49
-
/// e.g. send a text, send a reaction, create a new conversation, etc
50
-
}];
46
+
/// Do your IMCore/ChatKit stuff here
47
+
/// e.g. send a text, send a reaction, create a new conversation, etc
51
48
} else {
52
49
/// If it failed to connect to the daemon for whatever reason
53
50
NSLog(@"Couldn't connect to daemon :(");
54
51
}
55
52
```
56
53
57
-
Now, this is the basic context that you need to interface with IMAgent and run your IMCore/ChatKit code. Now that we've got that out of the way, just assume that the rest of the code in this article is being run within the `query` block above unless explicitly stated otherwise.
54
+
Now, this is the basic context that you need to interface with IMAgent and run your IMCore/ChatKit code. Now that we've got that out of the way, just assume that the rest of the code in this article is being run within the `if` block above unless it explicitly states otherwise.
58
55
59
56
## Sending a text
60
57
This was, by far, the most crucial function to get working. A web interface to simply browse your texts but not send any wouldn't get anyone's interest. This also did take me a significantly long time to get working, but that was due mainly to my own inability to read. [This page](https://iphonedevwiki.net/index.php/ChatKit.framework) on the iPhoneDevWiki has basic information about how to send a text to a pre-existing conversation, but when I read through it, I missed the section that said *"Note that this will still only work from the MobileSMS process, even though `[CKConversationList sharedConversationList]` is NOT always null in other processes."* Once I set up IPC with libmryipc, I was able to send information through the IPC to the MobileSMS process to send the text. Now, however, since I connect directly to the IMDaemon, I don't need to inject into the MobileSMS process to send a text. \
There is one caveat about the above code: It seemed to work fine on iOS 13, but when I've tried in on iOS 14, it appears that the sucess rate of sending an attachment drops to about ~20% or less. I don't know why this is, and as of October 17, 2020, I'm still working on figuring it out and making it work better. I'll try to update this document once I figure it out. \
90
-
If you'd prefer not to use ChatKit, but rather pure IMCore, I've found another way to send a message using only IMCore, but I haven't yet figured out how to attach attachments to the message. Once again, I'll update this document once I do figure that out (if I ever do). Here's the code:
86
+
If you'd prefer not to use ChatKit, but rather pure IMCore, I've found another way to send a message using only IMCore, but I haven't yet figured out how to attach attachments to the message. I'll update this document once I do figure that out (if I ever do). Here's the code:
91
87
92
88
```objectivec
93
89
__NSCFString *address = (__NSCFString *)@"+11231231234"; /// Must have the full phone number. just "1231234" wont work.
0 commit comments