Frequently Asked Questions
- 1 General Questions
- 1.1 Which interface do you recommend I use?
- 1.2 Are the parameters the same for PUSH and PULL?
- 1.3 What's the difference between NUR and NRCV status codes?
- 1.4 Why do Messages Expire?
- 1.5 What will happen if we send a premium MT to an account that is out of credit?
- 1.6 Does New Zealand support porting? If so, how can I identify the correct operator?
- 2 Security
- 3 Credentials
- 4 API Values
- 4.1 Is the 'application' field for us to specify? Or does it have to match something that the service is expecting?
- 4.2 What are the possible values NUR "error" field?
- 4.3 Is the purpose of the messageId solely for the use of the sender?
- 4.4 Can an account use multiple rateCode values?
- 4.5 Can I set the SMS expiration period?
- 4.6 Can I see when a recipient received a message on their handset?
- 4.7 Can I see when a recipient reads a SMS message I sent them?
- 4.8 How can we check if Bulletin Connect is available and responding?
- 4.9 What is the best way to retrieve incoming messages from Bulletin Connect?
- 5 Benefits and Restrictions
- 6 Branding and Marketing
- 7 More than simple SMS
- 7.1 Does the 160 character limit for single messages apply before, or after URL encoding?
- 7.2 Does Bulletin Connect support the following content?
- 7.3 In terms of the ringtones and operator logos etc - can't these be sent to the end-user via wap push or are they really completely different?
- 7.4 Can I send MMS?
- 7.5 What is WAP Push?
- 8 Billing
- 9 Recipient Issues
- 10 More Information
General Questions
Which interface do you recommend I use?
We recommend the REST style HTTP or HTTPS interface. This is where our development effort is focused - new features like multiple recipients and rich media delivery have been added to the HTTP method but not to SOAP or SMPP.
SOAP will still be around for a long time but as a legacy option. SMPP is available for clients but is limited to simple SMS messaging.
Are the parameters the same for PUSH and PULL?
Yes. The same parameters are used for both PUSH and PULL REST connections.
What's the difference between NUR and NRCV status codes?
- NUR generally means that the number is not routable and is likely to be of an incorrect format or invalid number. The number needs to be confirmed as being of valid format and could be tried again but is likely to fail again unless it is changed.
- NRCV indicates that a (most likely) temporary delivery issue has occurred within the carrier network and that it could be tried again. A retry is recommended after a short delay and may work even without changes in the number submitted.
Why do Messages Expire?
Message may not be delivered for a number of reasons including:
- Phone is turned off.
- Phone is out of range.
- Phone is in flight mode.
- Phone is unable to accept SMS (mail box full).
When this occurs the carrier may return an "EXP" status to Bulletin which will be passed on to you.
What will happen if we send a premium MT to an account that is out of credit?
This will result in the status code NRCV being returned.
Does New Zealand support porting? If so, how can I identify the correct operator?
Bulletin Connect will route according to the current IPMS database and will return Delivery Notifications on messages as per usual.
While the database is updated every day, the migration of users from one carrier to another can take several days.
Security
Can we use HTTPS for added security?
Yes. The interface is the same as HTTP, so the only change will be in the protocol portion of the URL used (https:// for SSL).
The SSL protocol allows the web browser or client application to communicate across a network to the server in a way designed to prevent eavesdropping, tampering, and message forgery. SSL provides authentication and communications confidentiality over the Internet using cryptography. Our servers utilise the latest web server technology which enables the use of SSL 3.0 (recommended) and TLS.
Using SSL will impact the debug process so if you have a HTTP environment for initial development and testing it will allow a quicker development cycle.
 | We recommend that HTTP (SSL) is used where ever security and message integrity is required for an application. |
Would it be possible to establish a SMPP bind over a VPN connection?
Yes. There are two options available to add security to your SMPP connection:
- Binding over a VPN connection is possible but would incur additional setup and ongoing connection fees.
- We are able to provide a SSL/TLS proxy onto the SMPP link (think of it as the equivalent of http vs https) if you are able to support it.
Option 2 would have the lower overhead and costs.
Credentials
How do I get the values for the 'user' and 'password' fields?
Your user ID and password will be provided after you apply for a Connection. If you need further assistance please Contact Support.
Does the password expire?
No, your password will not expire.
How can we request a new password?
Contact Support with your UserID. We may need to verify your identity before we can process this request and we will need to liaise with you so that no loss of service occurs. Once the password is changed on Bulletin Connect the previous password will no longer work.
Does the username expire?
No. The username is your primary Identity in the Bulletin Connect system. If you need a new ID then costs may apply. Contact Support for assistance.
API Values
Is the 'application' field for us to specify? Or does it have to match something that the service is expecting?
The application field can be anything you like, its not used by the API but can be useful for client diagnostics if you have multiple services.
What are the possible values NUR "error" field?
The error field contains any string value the carrier returns to us and is very carrier/SMSC/UAS/developer dependent.
Is the purpose of the messageId solely for the use of the sender?
Yes. Any replies to messages you send out will also include a messageId that will link the reply to your original message.
The ID provided by your service is a string of up to 50 characters. If you are persisting
this information to a database, that would be the field type to use.
The current format is a hexidecimal string. However, this has changed in the past and may change again without notice in future, so simply recording it verbatim is the preferred course to take.
Can an account use multiple rateCode values?
Yes. A single Bulletin Connect account can be used for all your messaging needs regardless of whether you have different premium billing/ short code requirements. Bulletin will assign a different rateCode for each short code so that when you want to set the short code you simply use the appropriate rateCode in your request.
Can I set the SMS expiration period?
No. Not at this time. If you require this feature then contact Bulletin.net.
Can I see when a recipient received a message on their handset?
Yes. Although a few networks do not provide the message status information most do. Ensure your Bulletin Connect account is configured to request status messages and then they will be available to you. Each status will contain a message ID to enable you to match it against your message records.
Can I see when a recipient reads a SMS message I sent them?
No. Standard SMS does not provide this sort of information. You may be able to obtain this sort of information using information from a webserver. For example send the recipient a WAP Push message containing a Unique URL then monitor your webserver logs for when that URL is activated.
How can we check if Bulletin Connect is available and responding?
The simplest way to check if Bulletin Connect is available and responding is to generate a message and check the response code. If you send to a recipient string that is known to be invalid (e.g. "test" or "live") with valid credentials then you will receive a 400 To address is not a number response. If you do not get this response then contact Bulletin.net.
Do not use a number for testing as this may incur costs regardless of delivery state.
What is the best way to retrieve incoming messages from Bulletin Connect?
There are two options (Polling and Pushing) to retrieve incoming messages, replies and status updates and it will depend on your network setup, resources and application requirements as to which best suits.
Polling is a client initiated connection to the Bulletin Connect server and reduces firewall and proxy issues that can occur with the push method. The client should check for messages on a regular basis and will receive a 200 result if there are messages waiting and a 204 if there are no messages. The polling loop period could be anywhere from every few seconds for mission critical high response applications to every minute for those applications with a lower responsiveness requirement.
To use the polling method see the User Guide.
The Push option entails Bulletin Connect connecting to a REST end point on your server each time a message (reply or status) is processed. Because the connection is only initiated when a message is processed, it is less resource intensive but it can be impacted by your hardware or network changes, firewalls or proxies and tends to be higher in maintenance overhead and debugging processes.
To use the push method contact Bulletin.net with details of the REST endpoints you want to use for both incoming messages and status updates (they can be the same).
In summary, the poll gives you more control over message processing and is SIMPLER to implement, support and make changes to in your application while being EASIER to manage on complex networks. However is is more resource intensive managing the polling process.
The push method is more EFFICIENT but harder to maintain and support as you may not receive messages because:
a) There are no messages, or
b) There is a communication error between servers (eg fireware or access issues).
Benefits and Restrictions
How Many Messages can be sent per minute?
If individual (customised) messages are prepared and sent then about 240 per minute can be sent through Bulletin Connect. However, if a duplicate message is sent to all recipients, and is prepared as a batch, then this can be increased significantly to 800 per minute.
The speed of message delivery will also be impacted by:
- Network connection speed between your client and Bulletin Connect.
- Method of connecting to Bulletin Connect (HTTP is faster than a SOAP connection).
- The destination carrier. Some carriers throttle message delivery based on their network requirements.
 | Warning Bulletin Connect must not be used for unsolicited SPAM or marketing messages. Users that do so may have the service restricted or cut off. Download the NZ Unsolicited Electronic Messages Legislation and ensure your service and procedures adhere to this Act. Users residing in other countries or sending messages to other countries (outside of NZ) must ensure that they comply with all applicable local laws. |
Can I send to more than one recipient?
Yes. The to parameter can be a SPACE Separated List of numbers in international format. For example:
to=6425987654 6178542544 12059955852
Ensure you URLencode the parameters.
Can I send and receive SMS by email using Bulletin Connect?
No. Bulletin Connect is an API for integrating with other software platforms such as CRM systems, websites and databases. It is meant for tight integration without the overhead and issues that email has (such as delays).
If you want to use email then the Bulletin Messenger service is worth considering.
How does Bulletin Connect handle Mobile Number Portability in New Zealand?
Mobile Number Portability (MNP) was introduced in New Zealand in April 2007. MNP allows mobiles to change networks while retaining their phone number.
Bulletin Connect receives a file each day, which contains details of numbers that have ported. This file is provided by a third party working in association with the carriers and it generally takes 2-3 days for a ported number to appear in this file after a number has changed networks. During the short time between the handset changing networks and us being told of the change, the handset will not receive messages from Bulletin Connect.
Any long term issues with ported numbers should be raised with Bulletin.net.
Branding and Marketing
Can the source number be set when sending a message?
Yes. This is usually done via Bulletin Connect using the rateCode value. To use this feature please contact Bulletin.net with details of the numbers you want to use and you will be provided with instructions on how to use rate codes in your message sending process.
Generally this is used when sending via Premium Billed Short Codes rather than the Bulletin Wireless default threading range of numbers.
Can the recipient see a name instead of a number when they receive a message?
Yes. Some networks do allow you to set a word or string of words as the number recipients see as the sender of an SMS. This is done via Bulletin Connect using rate codes.
To use this feature please contact Bulletin.net with details of the strings you want to use (some restrictions apply) and you will be provided with instructions on how to use rate codes in your message sending process.
| When using this feature the recipient will not be able to reply to the message. Please ensure you have alternative contact instructions in the message to allow users to unsubscribe. |
Source headers can be any alphanumeric with the following restrictions:
- No more than 11 characters in total
- Use only alphanumeric characters, eg:
- a-z or A-Z, or
- 0-9.
- No symbols or spaces.
Do we need to specify a 'rateCode' if the recipient won't be charged for the text?
No. The rateCode is provided by Bulletin if you need to send messages from specific numbers (MSISDNs). If no rate code is specified then the message will be sent with a source number from the standard Bulletin range.
When using a premium rate service, when is the user charged?
Premium billing is done using Short Codes. Premium billing may either be a higher than normal cost message or it may be a free message depending on your requirements and carrier restrictions.
Short codes are carrier dependent, but can generally be requested to:
- Bill on the MO request (message from handset to short code).
- Bill on the MT reply (message from the service to the handset using a short code).
More than simple SMS
Does the 160 character limit for single messages apply before, or after URL encoding?
Before. The URL encoding is required in order for the request to be submitted to Bulletin Connect Message. Once we receive it it is decoded and then submited to the the carrier in a format that they require. If you are not setting a fragmentationLimit on your request then ensure that the message length is less than 160 characters before URL encoding it.
Does Bulletin Connect support the following content?
Content Type | Supported |
|---|---|
| PlainText | Yes |
| Unicode | Yes |
| Mono Ringtone | No |
| Imelody | No |
| Operator Logo | No |
| MMS | In development. You can send a WAP Push message with content or send an SMS with a link to a page with content. |
| WAP Push | Yes. |
In terms of the ringtones and operator logos etc - can't these be sent to the end-user via wap push or are they really completely different?
WAP push is just a special message that contains a URL that is automatically handled by some handsets. The URL could be a picture link (eg GIF), a sound link (eg mp3), a movie link (eg 3gp), a j2me installer (eg a JAR), a web page (eg HTML) or any other web content and the phone will do the best it can.
Operator logos and ringtones are files that are generally delivered using a different message format so that the supported handsets can do some automatic handling. So while they should be able to be linked to a WAP push message, the user experience is going to be quite different compared to if they were sent properly.
Can I send MMS?
No. You send the recipient a WAP Push message with content or send an SMS with a link to a page with content. Some operators block WAP Push messages, please contact Bulletin prior to usage.
What is WAP Push?
WAP Push is a special type of SMS message that triggers actions on some (but not ALL) handsets allowing those handsets to handle messages such as web addresses, business cards and calendar appointments with ease.
While this automation and integration is great for those handsets that do support WAP Push messages, there are many that do not.
When a handset that does not support WAP Push messages receives one, it is normal for them to drop it without notification so you can not be confident that the message has been received.
Treat WAP Push messages carefully and ensure your target market (including carriers and handsets) can correctly receive the messages you send them.
Billing
When is a message billed to my account?
Not all carriers can provide good status information, and many charge for attempted message delivery. Bulletin reserves the right to charge for all messages we submit to the carriers.
This means if the carrier is unable to deliver the message or rejects the message the cost is already incurred.
Your contract may include provision for an alternative arrangement if you deliver to supported networks.
How can I tell if an MT message has been billed?
RCV status indicates the message was received on the handset and that would indicate that the carriers are most likely going to bill for it. However, while the billing completion rate for NZ is quite high (about 98% for these types of SMS services pushed through our connections) a RCV does not always mean that the carrier can bill and collect for it and therefore RCV is not a 100% guarantee of billing and revenue share.
Recipient Issues
You send one message but your recipient receives the same message repeatedly
This is rare but it does occur when the there is a communication glitch between the recipients handset and their network, that stops the phone from acknowledging that it has received the SMS.
When this happens the carrier continues to attempt to deliver the same message (as per its store and forward procedures) until it receives an acknowledgment from the phone. This situation results in multiple messages on the handset if the handset does not acknowledge properly (if they all have the same sender number and you are not using short codes then this is probably the situation).
We have found that doing a hard restart of the phone fixes the issue. The recipient should simply pull the battery from the handset, wait a few seconds, reinsert the battery and power the handset up again.
More Information
What's the difference between Bulletin Connect and Campaigner?
Bulletin Connect is a developer API that allows you to create your own SMS handler for inbound and outbound campaigns.
Campaigner is a consumer website that offers a range of SMS response and SMS forwarding functionality with an easy to use web interface.
For a comparison of features and benefits see the product comparison matrix.
Who do I contact for more information or help?
If your questions are not answered here or in the User Guide then contact Bulletin.net Support including the following information:
- Account name used in Bulletin Connect.
- Contact Phone Number (please include Country and time zone so we are able to call you if necessary).
- Specific details. Clearly state your intention or issue and provide all relevant details. It is better to provide more information than too little and in the process of gathering the information your solution may actually appear without further assistance being required. State what you are trying to do and what you have tried.
Where can I get a copy of the 'service rules'?
You can request a copy of the Service Rules here. As these are dictated by mobile network providers, they are subject to change.
Please provide an email address that they can be sent to and that any changes can be notified to in the future.
Does Bulletin offer Carrier Lookup functionality?
Bulletin subscribes to the Ported Number Database and uses this to route messages. This is not exposed to third parties as per conditions of use so can only be used for routing and not for look-up purposes.