| API for Submitting MMS Messages to NowSMS |  Search
|
|
NowSMS Support Forums ⬆ NowSMS Support - SMS Issues ⬆ Archive through December 09, 2003 ⬆ |
◄ ► |
| Author | Message | |||
| Bryce Norwood - NowSMS Support |
Submitting MMS Messages to the Gateway Applications can submit MMS messages to the Now SMS/MMS Gateway via any of the following protocols, which are described below: 1.) Now SMS/MMS Proprietary URL Submission via HTTP GET or POST 2.) MM7 – The MMS standard for applications to submit MMS messages to an MMSC. MM7 is an XML/SOAP based API where the MMS message is formatted in a MIME encoded XML document and posted to the server using an HTTP POST. 3.) MM4 – The MMS standard for connectivity between multiple MMSCs. MM4 is an SMTP based interface where the MMS message is posted to the server as a standard MIME encoded e-mail message. While the interface exists primarily for connectivity between multiple MMSCs, the Now SMS/MMS Gateway also makes this interface available to application developers that are more comfortable with the SMTP protocol. 4.) MM1 – The MMS standard for phones to send and receive MMS messages from an MMSC. This is an HTTP based protocol where applications can submit binary encoded MMS messages encoding according to the MMS Encapsulation Specification (application/vnd.wap.mms-message MIME type) to the gateway using HTTP POST. 5.) EAIF – This is a Nokia proprietary variation on the MM1 protocol which was defined as an interface for submitting messages to a Nokia MMSC. The interface is functionally similar to MM1, with additional HTTP headers defined. Now SMS/MMS Proprietary URL Submission The Now SMS/MMS Proprietary format for submission of an MMS message is the interface that is used by the “Send MMS Message” form in the web menu interface of the gateway. To submit a message via this interface, a user account must be specified on the “SMS Users” page of the configuration dialog. To submit it the same way that the "Send MMS Message" form does in the gateway's web menu interface, you need to do an HTTP POST in the "multipart/form-data" MIME type. Basically, when you POST, it would look something like this: POST / HTTP/1.0 Accept: */* Content-type: multipart/form-data; boundary="--boundary-border--" Content-length: xxxxx (size of content part of post) Authorization: username:password (base64 encoded) ----boundary-border-- Content-Disposition: form-data; name="PhoneNumber" +448080148324 ----boundary-border-- Content-Disposition: form-data; name="MMSFrom" sender@domain (or +38484753009) ----boundary-border-- Content-Disposition: form-data; name="MMSSubject" Message Subject ----boundary-border-- Content-Disposition: form-data; name="MMSText" An optional text part of the message. ----boundary-border-- Content-Disposition: form-data; name="MMSFile"; filename="original-filename.ext" Content-type: Mime/Type File data goes here ----boundary-border---- The content-type for the overall message is "multipart/form-data". As with other multipart MIME encoding, you must include a boundary that separates the multiple parts of the message. It is very important to set the Content-length: field to specify the length of the multipart content that follows (this is how the server knows your HTTP post is complete). The Authorization header specifies the username and password used to login to the gateway. It is in the format "username:password" and is Base64 encoded. Then, the content has a part for each form variable. The "PhoneNumber" variable is required, it is the phone number of the message recipient. The "MMSFrom" variable is optional. It is the "From:" address to be used in the MMS message. (If sending a pre-compiled MMS message, this is used for the notification only.) The "MMSSubject" variable is optional. It is the "Subject" line used in the MMS message. (If sending a pre-compiled MMS message, this is used for the notification only.) The "MMSText" variable is optional. It contains a text part of the message. The "MMSFile" variable is optional, and can be repeated multiple times. It contains binary file content for an uploaded file. If you're sending a pre-compiled MMS file, you'd only include the "MMSFile" variable once. If you're sending a message for the gateway to compile, you could include each of the individual message parts as a separate instance of the "MMSFile" variable. As an alternative to using the HTTP POST, if the content of the MMS message already exists on a web server, the “MMSFile” variable can be specified as a URL instead of the actual file content. In this case, the message can be submitted to the gateway with an HTTP GET request, instead of requiring HTTP POST. For example: http://127.0.0.1:8800/?PhoneNumber=xxxxxx&MMSFrom=sender@domain&MMSSubject=Messa ge+Subject&MMSText=An+optional+text+part+of+the+message&MMSFile=http://www.nowsm s.com/media/logo.gif The variables are the same as described above, except that in a GET request, the “MMSFile” variable must point to a URL. As with the POST request, the “MMSFile” variable can be repeated to specify multiple content files. MM7 Before submitting a message via MM7, a VASP (Value Added Service Provider) account must be defined to the Now SMS/MMS Gateway. This account is defined on the “MMSC VASP” page of the configuration dialog. To post to the Now SMS/MMS Gateway via MM7, you must connect to the HTTP port configured for the MMSC on the "MMSC" page of the configuration dialog. And you must perform an HTTP POST of the MM7 content to a URI of "/mm7", which is how the gateway knows that the VASP intends to submit in the MM7 format. The HTTP headers of your POST must include a "Content-length:" header, and it needs to either include an "Authorization:" header for Basic authentication using the username and password configured for the account, or it must originate from an IP address that matches the name configured for the VASP account. (If your software cannot generate an "Authorization:" header, it is possible to configure the account name for the VASP as an IP address, and in this case, the MMSC will recognise any connections from that IP address as being for this VASP account.) The "Content-type:" header in the POST should be one of the "multipart" types (usually "multipart/related"), and should include a "boundary=" parameter that delimits the different parts of the message. The first part of the multipart message is expected to be the XML for the MM7 request, and we're going to expect to see a <Recipients> section with at least one <To>, <Cc> or <Bcc> recipient specified. The second part of the multipart message is expected to be the content for the MMS message, and this in turn will usually be another MIME multipart structure. The following example is adapted from the official MM7 specification that is included in the 3GPP TS 23.140 specification: Note that this example does not include a SMIL file, and as part of the MMS content, you would probably want to include a SMIL file (application/smil), which this example does not include. Also note that the MM7 XML portion of the document (the first part of the main multipart content) should not use any Content-Transfer-Encoding, it should always be expressed without any encoding. For the portion of the document that includes the MMS content itself, you can use Content-Transfer-Encoding of either quoted-printable or base64, or no encoding can be specified in which case it is assumed that the binary data is to be included as is. POST /mm7 HTTP/1.1 Host: mms.omms.com Content-Type: multipart/related; boundary="NextPart_000_0028_01C19839.84698430"; type=text/xml; start="</tnn-200102/mm7-submit>" Content-Length: nnnn SOAPAction: "" --NextPart_000_0028_01C19839.84698430 Content-Type:text/xml; charset="utf-8" Content-ID: </tnn-200102/mm7-submit> <?xml version="1.0" ?> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header> <mm7:TransactionID xmlns:mm7="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-M M7-1-3" env:mustUnderstand="1"> vas00001-sub </mm7:TransactionID> </env:Header> <env:Body> <SubmitReq xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1 -3"> <MM7Version>5.6.0</MM7Version> <SenderIdentification> <VASPID>TNN</VASPID> <VASID>News</VASID> </SenderIdentification> <Recipients> <To> <Number>7255441234</Number> </To> <Cc> <Number>7255443333</Number> </Cc> <Bcc> <RFC2822Address>7255444444@OMMS.com</RFC2822Address> </Bcc> </Recipients> <ServiceCode>gold-sp33-im42</ServiceCode> <LinkedID>mms00016666</LinkedID> <MessageClass>Informational</MessageClass> <TimeStamp>2002-01-02T09:30:47-05:00</TimeStamp> <EarliestDeliveryTime>2002-01-02T09:30:47-05:00</EarliestDeliveryTime> <ExpiryDate>P90D</ExpiryDate> <DeliveryReport>true</DeliveryReport> <Priority>Normal</Priority> <Subject>News for today</Subject> <DistributionIndicator>true</DistributionIndicator> <Content href="cid:SaturnPics-01020930@news.tnn.com" allowAdaptations="true"/> </SubmitReq> </env:Body> </env:Envelope> --NextPart_000_0028_01C19839.84698430 Content-Type: multipart/mixed; boundary="StoryParts-74526-8432-2002-77645" Content-ID:<SaturnPics-01020930@news.tnn.com> --StoryParts-74526-8432-2002-77645 Content-Type: text/plain; charset="us-ascii" Science news, new Saturn pictures... --StoryParts-74526-8432-2002-77645 Content-Type: image/gif Content-ID:<saturn.gif> Content-Transfer-Encoding: base64 R0lGODdhZAAwAOMAAAAAAIGJjGltcDE0OOfWo6Ochbi1n1pmcbGojpKbnP/lpW54fBMTE1RYXEFO ... --StoryParts 74526-8432-2002-77645-- --NextPart_000_0028_01C19839.84698430-- MM4 Before submitting a message via MM4, a VASP (Value Added Service Provider) account must be defined to the Now SMS/MMS Gateway. This account is defined on the “MMSC VASP” page of the configuration dialog. To post to the NowSMS MMSC via MM4, your application is making an SMTP connection to the MMSC, and you would connect to the "SMTP Port Number" that is configured on the "MMSC" page of the configuration dialog. To submit a message via MM4, the VASP must authenticate via SMTP using the "AUTH LOGIN" approach, or similar to the way it works for MM7, the VASP account can be created with an IP address as the "Account Name", and in that case any connection from that IP will be accepted as being a connection from that VASP account. "AUTH LOGIN" is rather simple. Basically, as part of the SMTP dialog, after the initial HELO or EHLO command, the SMTP client needs to issue the command AUTH LOGIN. The SMTP server responds with a "300" series code and prompts for the account name (the prompt after the code is a BASE64 encoded string). The client sends the account name as a BASE64 encoded string. The SMTP server responds with another "300" series code prompting for the password, and the client responsds with the password as a BASE64 encoded string. A "200" series response indicates that the authentication was accepted, a "500" series response indicates that it was not. The SMTP dialog then continues as normal, generally with a "MAIL FROM:" command from the client indicating the sending address of the message, followed by one or more "RCPT TO:" commands to indicate the recipients for the message. Note that NowSMS expects the "RCPT TO:" addresses to be in a format of phonenumber@domain.name or phonenumber/TYPE=PLMN@domain.name, where "domain.name" is the "Domain Name for MMS E-Mail" configured on the "MMSC" page of the configuration dialog. (The "Local Host Name or IP Address" value is also acceptable here.) If the domain name is not present, the MMSC will reject the recipient. As special support for Multimedia WAP Push, the following address formats are also supported to specify Multimedia WAP Push to be used for sending to the phone number: phonenumber.wappush@domain.name or phonenumber/TYPE=WAPP@domain.name. The actual MMS message is then transmitted via the "DATA" command. Normally an MMS message would be a multipart MIME message with multiple content parts, although NowSMS will also accept a message that includes only a single part. The MM4/SMTP dialog looks something like this: The dialog looks something like this (IN means from server, OUT means from client): IN: 220 SMTP Ready OUT: HELO client.name (or EHLO client.name) IN: 250 OK (or a multiline response if EHLO was used) OUT: AUTH LOGIN IN: 334 VXNlcm5hbWU6 ("Username:" BASE64 encoded) OUT: dGVzdA== ("test" BASE64 encoded) IN: 334 UGFzc3dvcmQ6 ("Password:" BASE64 encoded) OUT: dGVzdA== ("test" BASE64 encoded) IN: 235 Ok OUT: MAIL FROM: <username@domain.com> IN: 250 Ok OUT: RCPT TO: <+447778889999/TYPE=PLMN@mms.domain.com> IN: 250 Ok OUT: DATA IN: 354 Ok, end with "." on a new line... OUT: (Transmit MIME encoded message, then end with a line with only the . character) IN: 250 Message Accepted OUT: QUIT Using the example data from the MM7 message above, the MIME encoded message would look something like this: To: +447778889999/TYPE=PLMN@mms.domain.com From: username@domain.com Subject: News for today Content-Type: multipart/mixed; boundary="StoryParts-74526-8432-2002-77645" Content-ID:<SaturnPics-01020930@news.tnn.com> --StoryParts-74526-8432-2002-77645 Content-Type: text/plain; charset="us-ascii" Science news, new Saturn pictures... --StoryParts-74526-8432-2002-77645 Content-Type: image/gif Content-ID:<saturn.gif> Content-Transfer-Encoding: base64 R0lGODdhZAAwAOMAAAAAAIGJjGltcDE0OOfWo6Ochbi1n1pmcbGojpKbnP/lpW54fBMTE1RYXEFO ... --StoryParts-74526-8432-2002-77645-- MM1 Before submitting a message via MM1, a VASP (Value Added Service Provider) account must be defined to the Now SMS/MMS Gateway. This account is defined on the “MMSC VASP” page of the configuration dialog. To post to the Now SMS/MMS Gateway via MM1, you must connect to the HTTP port configured for the MMSC on the "MMSC" page of the configuration dialog. And you must perform an HTTP POST of the MM1 content to a URI of "/mm1", which is how the gateway knows that the VASP intends to submit in the MM1 format. The HTTP headers of your POST must include a "Content-length:" header. To specify the username and password of the VASP account, you must either include an "Authorization:" header for Basic authentication using the username and password configured for the account, or the username and password can be specified on the request URI (e.g., /mm1/username=password). Alternatively, the request must originate from an IP address that matches the name configured for the VASP account. (If your software cannot generate an "Authorization:" header, it is possible to configure the account name for the VASP as an IP address, and in this case, the MMSC will recognise any connections from that IP address as being for this VASP account.) The "Content-type:" header in the POST should be "application/vnd.wap.mms.message", and the message should be a binary MMS message of the m-send-req format, formatted according to the MMS Encapsulation Specification, published by the Open Mobile Alliance. Consistent with HTTP specifications, a "400" or "500" series HTTP response would be considered an error condition. The MMSC might return a "200" series response even if an error did occur, in which case information would be included in the "X-Mms-response-status" field of the MM1 response (MIME type "application/vnd.wap.mms-message", X-Mms-Message-Type of "m-send-conf") would contain a response-status value other than Ok. EAIF Before submitting a message via EAIF, a VASP (Value Added Service Provider) account must be defined to the Now SMS/MMS Gateway. This account is defined on the “MMSC VASP” page of the configuration dialog. To post to the Now SMS/MMS Gateway via EAIF, you must connect to the HTTP port configured for the MMSC on the "MMSC" page of the configuration dialog. And you must perform an HTTP POST of the EAIF content to a URI of "/eaif", which is how the gateway knows that the VASP intends to submit in the EAIF format. The HTTP headers of your POST must include a "Content-length:" header. To specify the username and password of the VASP account, you must either include an "Authorization:" header for Basic authentication using the username and password configured for the account, or the username and password can be specified on the request URI (e.g., /eaif/username=password). Alternatively, the request must originate from an IP address that matches the name configured for the VASP account. (If your software cannot generate an "Authorization:" header, it is possible to configure the account name for the VASP as an IP address, and in this case, the MMSC will recognise any connections from that IP address as being for this VASP account.) The "Content-type:" header in the POST should be "application/vnd.wap.mms.message", and the message should be a binary MMS message of the m-send-req format, formatted according to the MMS Encapsulation Specification, published by the Open Mobile Alliance. MMS message recipients can be specified either in the MMS message content itself, or in the "X-Nokia-MMSC-To:" header. Consistent with HTTP and EAIF specifications, a "400" or "500" series HTTP response would be considered an error condition. The expected response for a valid message submission would be an HTTP "204" response that includes an "X-Nokia-MMSC-Message-Id:" header. (In beta releases of the v5.0 Now SMS/MMS Gateway, the MMSC might return a "200" series response even if an error did occur, in which case information would be included in the "X-Mms-response-status" field of an MM1 response with the "X-Mms-Message-Type" field containing a response-status value other than Ok. We expect this to have been corrected prior to the v5.0 release.) | |||
