XML-RPC Protocol Method: sendmessage

From Dreamwidth Notes
Jump to: navigation, search
Needs Update: This documentation was ported over from LJ's Server Manual with minimal modification. It may not match Dreamwidth's implementation of the method, and needs to be double checked against the DW code and updated as necessary.

Send a private message to a user's inbox.

Inputs

username Scalar. Required. Username of user logging in.

auth_method Scalar. Optional. Authentication method used for this request. The default value is "clear", for plain-text authentication. "cookie" and any of the challenge-response methods are also acceptable.

password Deprecated. Scalar. Optional. Password of user logging in in plaintext. If using the "clear" authentication method, either this or "hpassword" must be present.

hpassword Deprecated. Scalar. Optional. MD5 digest of user's password. Not much more secure than password, but at least it's not in plain text.

auth_challenge Scalar. Optional. If using challenge-response authentication, this should be the challenge that was issued to you by the server.

auth_response Scalar. Optional. If using challenge-response authentication, this should be the response hash that you generate, based on the formula required for your challenge.

ver Scalar. Optional. Protocol version supported by the client; assumed to be 0 if not specified. See Protocol Versions for details on the protocol version.

to Array of scalars. Required. The username for each message recipient. Each recipient must refer to an account who is able to receive DW private messages. Including usernames that refer to communities, suspended, or deleted accounts will cause the method to fail and the message will not be sent.

subject Scalar. Required. The subject for this message. Limited to 255 characters. No newlines.

body Scalar. Required. The body text for this message, no HTML. Limited to 5,000 characters for free accounts and 10,000 characters for paid accounts. Since there is no way currently to tell if an account is paid or free through XML-RPC, the client should assume a 5,000 character limit. Any HTML in the message will be interpreted as plain text.

parent Scalar. Optional. The id of the parent message. If the message you are sending is a reply to another message, this is the id of the message you are replying to. (See getinbox)

Example Request

POST /interface/xmlrpc HTTP/1.0
User-Agent: XMLRPC Client 1.0
Host: www.dreamwidth.org
Content-Type: text/xml
Content-Length: 1034
 
<?xml version="1.0"?>
<methodCall>
  <methodName>LJ.XMLRPC.sendmessage</methodName>
  <params>
    <param>
      <value><struct>
        <member>
          <name>username</name>
          <value><string>test</string></value>
        </member>
        <member>
          <name>password</name>
          <value><string>test</string></value>
        </member>
        <member>
          <name>auth_method</name>
          <value><string>clear</string></value>
        </member>
        <member>
          <name>to</name>
          <value><array><data>
            <value><string>test_recipient1</string></value>
	    <value><string>test_recipient2</string></value>
	  </array><data></value>
        </member>
        <member>
          <name>subject</name>
          <value><string>Test</string></value>
        </member>
	<member>
          <name>body</name>
          <value><string>This is my test message.</string></value>
        </member>
      </struct></value>
    </param>
  </params>
</methodCall>

Outputs

sent_count Scalar. Required. The number of messages generated by your request.

msgid Array of scalars. Required. The ids of each message generated by your request. The ids appear in the order you placed the usernames in the 'to' member.

last_errors Array of scalars. Optional. If there were any problems encountered after your message was approved to be sent, this member will give you a description of the problem. Usually if there are any big problems, your request will simply fail instead of including 'last_errors'.

Example Response

POST /interface/xmlrpc HTTP/1.0
User-Agent: XMLRPC Client 1.0
Host: www.dreamwidth.org
Content-Type: text/xml
Content-Length: 474
 
<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value><struct>
        <member>
          <name>sent_count</name>
          <value><int>2</int></value>
        </member>
        <member>
          <name>msgid</name>
          <value><array><data>
            <value><int>102365</int></value>
            <value><int>103215</int></value>
          </data></array></value>
        </member>
      </struct></value>
    </param>
  </params>
</methodResponse>