Blocked Words.

We’ve recently added a new, ‘blocked words’ feature to the Text-Connect Send function.

This is a response to anti fraud regulation and means that text messages containing some words will not send.  Instead you will receive a message at the top of the send screen asking you to contact us.

Typically words associated with financial institutions, insurance and some other subjects are affected.

To confirm:

  • Remove any candidate words
  • Schedule the message for later (next week)
  • Send

If the message Sends, delete the pending message in the outbox and you are OK to resend your messages.

 

 

Developer API. Troubleshooting

Having trouble sending text messages via our Text-Connect API?

Here are some things to help you identify the cause.

Step 1: Are you receiving an error code?

No: Go to Step 2

Yes: See the specific error code below for more information.

Code Description
-100 Not Enough Credits
-101 Invalid CreditID
-200 Invalid Contact
-300 General Database Error
-301 Unknown Error
-302 Return XML Error
-303 Received XML Error
-400 Some numbers in list failed
-401 Invalid Destination Address
-402 Invalid Source Address – Alphanumeric too long
-403 Invalid Source Address – Invalid Number
-404 Blank Body
-405 Invalid Validity Period
-406 No Route Available
-407 Invalid Schedule Date
-408 Distribution List is Empty
-409 Group is Empty
-410 Invalid Distribution List
-411 You have exceeded the limit of messages you can send in a single day to a single number
-412 Number is blacklisted
-501 Unknown Username/Password
-502 Unknown Action
-503 Unknown Message ID
-504 Invalid From Timestamp
-505 Invalid To Timestamp
-506 Source Address Not Allowed (Email2SMS)
-507 Invalid/Missing Details
-508 Error Creating User
-509 Unknown/Invalid User
-510 You cannot set a user’s credits to be less than 0
-511 The system is down for maintenance
-512 User Suspended
-513 License in use
-514 License expired
-515 No License available
-516 Unknown List
-517 Unable to create List
-601 Unknown Report Type
-701 No UserID Specified
-702 Invalid Amount Specified
-703 Invalid Currency Requested

 

Step 2: The issue is likely with your application

If you are experiencing problems using the API and not receiving an error code in return the most likely cause is that we are not receiving anything from your application. Please check that you are using the correct api url:

  • HTTP: https://goto.text-connect.co.uk/api

If this is correct, we suggest you check everything is as it should be by referring back to the HTTP  documentation.

 

Step 3: Additional things to try

i. Can you traceroute (windows: tracert) to goto.text-connect.co.uk

ii. Can you telnet from that machine to goto.text-connect.co.uk (port 80)

iii. Does it work from another machine?

If you believe everything to be correct please contact us.

Please note that due to the technical nature of the API our operators may need to confer with a specialist.

HTTP API Documentation

 

Connecting to the API

The URL for accessing the API from within your script is: https://goto.text-connect.co.uk/api

The API can be called with an HTTP GET or POST, passing in the relevant parameters. All parameters are mandatory unless otherwise stated. All parameters must be URI Encoded.

General Parameters

The general parameters are applicable to all calls to the API

Parameter Name Description
Token (required) Your token (found in your settings within you online Text-Connect account)
Action (required) The action that you would like to perform. This must be one of (not case sensitive):
CheckCredits to check how many credits you have
CheckMessageStatus to check the status of a message
Send to send a message
Report to create a report
CreateUser to create a new user
UpdateCredits to add/remove credits from an existing user
ImportContactsCSV to import contacts
DeleteAllContacts to delete all contacts
DeleteAllGroups to delete all contact groups
ShowErrorMessage (optional) If this is set (to any value) and an error occurs in the API call, the text for the error message will be shown one line beneath the error code.

Check Credits

Checks your current credit balance. No further parameters are required. Your credit balance will be returned in the content of the page.

Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=CheckCredits

Check Message Status

Parameter Name Description
MessageID The Message ID of the message that you wish to query. This is the ID returned by the Send action and can also be found in a message report
Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=CheckMessageStatus&MessageID=[Your Message ID]

Send Message

Sends a message. The message ID or error code will be returned in the content of the Page. If multiple numbers are submitted, then multiple IDs / error codes will be returned, separated by commas

Parameter Name Description
DestinationAddress The Destination Address(es) to send the message to. If you wish to send to multiple numbers, they should be separated by a comma. When submitting multiple numbers, you should use the POST method rather than the GET method.To send to a list, set the DestinationAddress parameter to “List” and add a new parameter “ListName” with the name of the list to send to.For a group set the DestinationAddress parameter to “Group” and add a new parameter “GroupName” with the name of the group to send to.If the send is successful, the API will return 1. If not, a negative error code will be returned.Note that these sends may occur in the background if the group/list contains more than 200 entries.
SourceAddress The Source Address for the message. If this is alphanumeric, it must be 11 or less characters. All GSM characters are valid, however operators and handsets may support restricted character sets. We recommend you stick to A-Z, a-z, 0-9 and space.
Body The Message Body (max 459 characters)
ScheduleDate (optional) The date that the message should be sent (YYYYMMDDHHMMSS)
SourceTON (optional) The Type Of Number for the source address (1 for international, 5 for alphanumeric)
ValidityPeriod The period in seconds that the message will be tried for (maximum 86400 = 24 hours). Once this expires, the message will no longer be attempted to be delivered.
GetAllMessageIDs If the message is longer than 160 characters, the system by default will return only the first ID for each message. Set this parameter to 1 to return all the Ids for each part of each message.
GetBGSendID If you send to a distlist and set this parameter to 1 the BGSendID for the dist list will be returned. For future proofing, this could be a comma separated list of values, should the send be split into multiple sends.
Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=Send&DestinationAddress=[Your Number]&SourceAddress=API&Body=Hello%20World

Reports

Retrieve the data from a report. The report, in CSV format, will be returned in the content of the page.

Parameter Name Description
ReportType The Type of report. Options are: Outbox (From and To dates are ignored for this report), Messages, Usage, InboundMessages, FailedMessages
From The start date for the report (YYYYMMDDHHMMSS)
To The end date for the report (YYYYMMDDHHMMSS)
Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=Report&ReportType=Messages&From=20130704000000&To=20130711000000

Create User

Only possible if you are an admin user, this will create a child user. If successful, ‘1’ will be returned in the content of the page. If unsuccessful, the first line of the page will be the error code and the following lines will contain text information about the nature of the error(s).

Parameter Name Description
ChildUsername The username of the user you wish to create
ChildPassword The password for the user
AccessLevel What access level the user should have (Normal or Admin)
FirstName The first name of the user
LastName The last name of the user
Email The email address of the user
Telephone (Optional) The telephone number of the user
Credits How many credits the user should start with (these will be deducted from your account)
Credit Reminder (Optional) When to send the user a low credit warning email (number of credits left to trigger the email)
Alert (Optional) After how many days of inactivity should an inactivity alert be sent
Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=CreateUser&ChildUsername=[Child Username]&ChildPassword=[Child Password]&AccessLevel=Normal&FirstName=[User’s First Name]&LastName=[User’s Last Name]&Email=[User’s Email]&Credits=5

Update Credits

Transfer credits to/from a child user. If successful, ‘1’ will be returned in the content of the page.

Parameter Name Description
ChildUsername The username of the user that you wish to transfer credits to/from. The user must belong to you.
Quantity The amount of credits to transfer. If the number is positive, credits will be transferred to that user. If the number is negative, they will be transferred from that user to you.
Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=UpdateCredits&ChildUsername=[Child Username]&Quantity=5

Import Contacts CSV

This allows you to import contacts into your address book.

For each line in the ContactsCSV parameter, a corresponding line will be returned in the content of the page in the format:

[line] : [result]

Where result is one of:

Success
Duplicate Name
Duplicate Number
Partial
Failed

If there are any Partial or Failed lines, then there will be a blank line, followed by text with details of all the errors below. Partial will usually mean that the contact was added, but could not be put in the group.

Example:

ContactsCSV Parameter contains:
Contact 1,447777777771,noone@anywhere.com,group1
Contact 2,447777777772,
Contact 3,447777777773,,group1,group2,group3
,447777777774,noone@anywhere.com,group3
Contact 5,mynumber,noone@anywhere.com,group3

Gives the reponse:

1 : Success
2 : Success
3 : Success
4 : Failed
5 : Failed

Errors:

4 : No name
5 : Invalid number (mynumber)

Parameter Name Description
ContactsCSV A comma separated list of contacts to add, one per line formatted as follows: name,number,email,group1,group2,group3
IgnoreDupes (Optional) If set to 1, the system will allow duplicate contacts (name or number) to be created. By default the system will not allow duplicate names or numbers in contacts.
OverwriteDupes (Optional) is set to 1, the value of IgnoreDupes is ignored.
OverwriteDupes (Optional) is set to 1, then any duplicate number will be overwritten. If a duplicate name exists, but with a different number, the original contact will not be overwritten, instead a new contact will be created.
Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=ImportContactsCSV&ContactsCSV=contact%201%2C447777777777%2Cnoreply%40anywhere.com%2Cgroup1%2Cgroup2%2Cgroup3%0Acontact%202%2C447777777778%2Cnoreply%40anywhereelse.com%2Cgroup1%2C

Delete All Contacts

Deletes all contacts in this account. No further parameters are required. 1 will be returned if the deletion was successful, the relevant error code will be returned if an error occurred.

Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=DeleteAllContacts

Delete All Groups

Deletes all groups. No further parameters are required. 1 will be returned if the deletion was successful, the relevant error code will be returned if an error occurred.

Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=DeleteAllGroups

Empty Group

Remove all contacts from the specified group

Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=EmptyGroup&Group=MyGroupName

Delete Group

Delete the specified group

Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=DeleteGroup&Group=MyGroupName

GetBGMessages

Returns a JSON array of MessageID/Number/Status objects (e.g. [{“MessageID”:”3509592″,”Destination”:”447777777777″,”Status”:”Sent”},{“MessageID”:”3509593″,”Destination”:”447777777778″,”Status”:”Sent”}]
or a json error array as follows: {“error”:”-521″,”message”:”Unknown Background SendID”}

Possible errors:
-521 : Unknown Background Send ID
-522 : Background Send Not Finished
-523 : No messages were found

This function will be unable to access messages that have been archived.

Parameter Name Description
BGSendID ID of the send you want to retrieve messages for.
Example GET URL : https://goto.text-connect.co.uk/api?Token=th1S-15my-t0ken&Action=GetBGMessages&BGSendID=[BGSendID]

Inbound Message HTTP Forwarding

If you have bought an Virtual Mobile Number (VMN or MSISDN), you can set up the system to forward messages sent to that VMN to a web page on your website.

To do this, login into the web interface, go to your inbox and click on the manage button for the VMN you want to forward.

Once there you will be able to choose the URL to forward to, whether you want to forward with the GET or POST method and what to pass with the auth parameter. (The auth parameter is a passthrough variable designed to add some security by having a password passed through)

The following parameters are used in the call to your site:

source – the phone number that the message came from

dest – the VMN that the message was received on

msg – the body of the message

id – the ID of the message

receivedts – the timestamp that the message was received by us in the format YYYY-MM-DD HH:MM:SS

auth – the passthrough variable defined in manage VMN on the web interface

Supplemental Data from a Distribution List

If you have selected a distribution list to receive supplemental data from, you will receive the following additional parameters, with data from the mail merge fields of that list

MMName – the data from the Name field

MMEmail – the data from the Email field

MM1 – the data from the first mail merge field

MM2 – the data from the second mail merge field

MM3 – the data from the third mail merge field

MM4 – the data from the fourth mail merge field

MM5 – the data from the fifth mail merge field

Error Codes

Code Description
-100 Not Enough Credits
-101 Invalid CreditID
-200 Invalid Contact
-300 General Database Error
-301 Unknown Error
-302 Return XML Error
-303 Received XML Error
-400 Some numbers in list failed
-401 Invalid Destination Address
-402 Invalid Source Address – Alphanumeric too long
-403 Invalid Source Address – Invalid Number
-404 Blank Body
-405 Invalid Validity Period
-406 No Route Available
-407 Invalid Schedule Date
-408 Distribution List is Empty
-409 Group is Empty
-410 Invalid Distribution List
-411 You have exceeded the limit of messages you can send in a single day to a single number
-412 Number is blacklisted
-414 Invalid Group
-501 Unknown Username/Password
-502 Unknown Action
-503 Unknown Message ID
-504 Invalid From Timestamp
-505 Invalid To Timestamp
-506 Source Address Not Allowed (Email2SMS)
-507 Invalid/Missing Details
-508 Error Creating User
-509 Unknown/Invalid User
-510 You cannot set a user’s credits to be less than 0
-511 The system is down for maintenance
-512 User Suspended
-513 License in use
-514 License expired
-515 No License available
-516 Unknown List
-517 Unable to create List
-518 Blank or Invalid Source Address
-519 Blank Message Body
-520 Unknown Group
-601 Unknown Report Type
-701 No UserID Specified
-702 Invalid Amount Specified
-703 Invalid Currency Requested

Manage your Text-Number

Below we’ve covered the normal routine for adding and managing Text-Numbers on your text connect account.

Your Text-Number has a number of settings you can control…..

  • Number Name: Giving your Text-Number a name makes it easier to manage multiple numbers on your Text-Connect account.
  • Auto Response: Setting and enabling an Auto Response means that anyone texting your number will automatically receive your auto response message in reply.  It means that you can let the sender know that their message has been received. The keyword section gives additional options.
  • Forwarding: Use this section to automatically forward all incoming text messages to:
    • Other mobile numbers.
    • Email addresses.
    • HTTP web servers for custom message handling via your own software systems.
  • Distribution List Triggering: Trigger a text message to one of your Distribution lists with a text from your mobile phone. Add the numbers of the mobile phones you want to allow to use this feature, separated by commas.

The ‘trigger’ text message must be formed in a specific format and from one of the numbers you specify above:  The distribution list name (must be one word),  ‘From’ name, followed by your text message. (e.g. ListName From this is the message to be sent). The phone which triggers the message shot will receive a text message to confirm a successful trigger.

For help triggering a distribution list call us on 01952 820 453.

You can login to Text-Connect and manage your Inbound Text-Numbers here.

Advanced Send. More options.

Use the ‘Advanced’ tab on the Send page and send messages to multiple recipients (lists, groups, contacts) at the same time.

The Advanced option, found under the main ‘Send’ page, gives you additional options for mixing recipients from your contacts, contact groups and lists as well as other additional sending options. Advanced Send.

  1. To: Choose numbers from your contacts, groups, or freehand type,  plus select by name. Separate multiple numbers with comma’s.
  2. Add: Use the add button to select and add recipient numbers to the ‘To’ field.
  3. From: Decide if you are going to use a Text-Label or your Text-Number.  Click on the best option for your message.
  4. Message text: Here you can enter the message you are sending.
  5. Insert Template: Text-Connect gives you the option of setting up predefined message templates. Select from your templates here.
  6. Immediately: Send your message ‘Right now’ by clicking “Send Message”.
  7. On a later date: This will schedule the message to be sent later, and you will be able to check it in your Outbox. If you cancel the message from your Outbox, used credits will be restored to your balance. This is a good way of checking messages before sending ‘Live’.
  8. By schedule: Choose to send your message multiple times as per a schedule you define.

Please login to send your text messages here.

Text message delivered ?

When you click ‘Send’, a series of live delivery reports will appear on your screen, which show the status of your message. Messages are usually delivered very quickly, so you may not see them all.  As a successful delivery can complete very fast you may not see all of these statuses…

  1. Pending: the message is on its way to the mobile network hosting your recipients phone.
  2. Sent: the message has been passed to the mobile network and they are sending it on to your recipient’s phone. Text-Connect are waiting on them to confirm delivery.
  3. Delivered: Your message has reached your recipients phone, as confirmed by their mobile network.

If your message is delayed or fails, you may see other status updates:

  • FAILED: Your message did not reach the recipient.
  • UNKNOWN – The status of your message is not currently known, we have had no information from the mobile network regarding it’s delivery or failure.
  • EXPIRED – Your text message was not delivered to the phone within the required time. The phone may broken or switched off.
  • COMMAND_REJECTED – There is a problem with the phone number. It’s possibly incorrect or not current.
  • UNDELIVERABLE – Your text has not reached the phone. Similar to Command_Rejected, there may be a problem with the number.
  • COMMAND_FAILED – As per ‘undeliverable’ but for international messages.

If you are sending several text messages in quick succession, you can keep up to date on their delivery status by clicking the ‘Sent’ folder.

Schedule your Message

When to send. Now or pre schedule for the future ?

Once you have your message ready to send, you can choose when it is sent.

Text-Connect gives you 3 options:

  1. Send ‘immediately‘.  Send right now.
  2. Send ‘on a later date‘.  Schedule for a date and time in the future.
  3. Send ‘by schedule‘.  Schedule multiple sends over a time period.

Writing your text message.

Composing: things to bear in mind…

For each 160 characters you use in your text message to a UK mobile number, 1 credit will be used. 160 is the standard length for a SMS text message, however there are some instances noted below that are worth keeping in mind:

  • Using Text-Connect you can send ‘Long’ messages which give you more scope when communicating complex information.  You can draft long messages up to 456 characters in length (effectively 3 messages long) and this will use 1 credit per 160 character block.
  • Be sure to check the character & message count as you type to see how many credits your message will use.
  • Your messages sent to mobile numbers outside of the UK will use 2 credits per 160 character message. Please call for more information on our International coverage.
  • Some ‘special’ characters (e.g. £, $, &) are counted as 2 because they are not part of the standard GSM character set (a to z, 0 to 9). This could push you over the 160 character, 1 credit threshold for your message.

You can login to Text-Connect to start composing a message here.

Sending a Text. ‘From’ settings.

When sending a text, you need to specify the ‘From’ information.

The ‘From’ field can be either a a Text Label or your Text-Number.

Text label.

If you choose to use a Text Label you should keep it no longer than 11 alphanumeric characters. An alphanumeric text label means A to Z, 0 to 9 but does should not use spaces or special characters (ie.  &^$£”% etc).

If you choose to use a Text Label you will not be able to receive replies back to your Text-Connect account via your text number.

NB: If you choose a text label that is only 2 characters long, some handsets (often I-Phones) may not display it correctly.

Text-Number.

If you have a Text-Number on your Text-Connect account you can choose this as the ‘From’ label. Click the ‘Virtual Mobile Number’ tab on the ‘Send’ box to select. Reply’s to your message will then be delivered to your inbox.

If you do not have a Text-Number and would like reply’s delivered back to your Text-Connect inbox, order online or give us a call on 01952 820 453.

Send a Text. Choosing Recipients

Choosing your recipients: We give you 5 options:

Text-Connect has been designed to make it quick, easy and flexible to send your text messages. We give you 5 different ways to select who to send to:

Choose from one of the following options:

  1. Type in the Number manually.
  2. Choose a single Contact from your Text-Connect address book.
  3. Select a Group of contacts from your Text-Connect address book.
  4. Select an uploaded Distribution List of your numbers.
  5. Upload a Campaign List from the ‘Send’ page for a one-off broadcast.