Over the past six months I’ve been developing a Student Management System based on Dynamics CRM 2011 for one of the new Trades Academies. I’ll talk about why we chose Dynamics CRM in a later post, but this post is about the integration I built with the TextaHQ SMS Messaging service.

TextaHQ was attractive for no monthly fees, low per message cost and a two way API allowing SMS replies. When replies come back the gateway sends the reply to a Callback URL allowing us to save the message straight into CRM. Not so great if your server goes down for a few hours, but it does mean we don’t have to be running a service to poll for new messages like some APIs.

I would love to have published this up into a nice how to guide but probably not going to have time to do that for a while, so I thought I’d code dump for now instead.

My solution consists of three parts, the SMS Message entity, the plug-in assemblies for sending the messages and a ASP.NET form to save the messages back into CRM.

SMS Message Entity

A new ‘activity’ entity named SMS Message

• Add a field named characters remaining (see the Magnetism blog for how to implement the Javascript to count your characters remaining)
• Add a field named sendernumber – this is where the sender number of mobile replies will be put
• These are the status codes I am using:
  • Open
    • Draft (1) – Default Value
    • Failed (352,400,004)
  • Completed
    • Pending Send (352,400,002) – Default Value
    • Sent (352,400,000)
    • Delivered (352,400,006)
    • Received (352,400,001)
  • Cancelled
    • Cancelled (3) – Default Value
• Setup the form – this is what mine looks like
  

Plug-in Assemblies

Create a  Web Resource called ‘smsconfig’ – an XML file. Format it like below with the URL and API key from your TextaHQ account

<configuration>
<url>http://app.nz.textahq.com/api/sendSMS.php</url>
<key>123456789012345678901234567890</key>
</configuration>

Download the source code for the Dynamics CRM plug-in assemblies SMS Messaging source code

There are four files in the source code –

Utilities.cs

Contains a (rather bad) phone number cleaning method; a method to read the url & key from the configuration XML file; code for querying the ‘smsconfig’ web resource and the code to post the message to the gateway

StatusCodes.cs

Contains the definitions of the statuscodes I defined above

SendSMS.cs

The code that should be triggered when the statuscode of the smsmessage entity is updated

It basically:

• Checks if the status code is in ‘Completed_Pending’ send state (user clicks ‘Save and Complete’ on the SMS Message activity’)
• Retrieve the needed data from fields, check the message isn’t blank
• If the regarding entity is a contact, sends the message to the contact
• If the regarding entity is a course (you can delete this functionality if you like), it sends the message to all of the contacts enrolled in the course with a mobile phone
• Updates the SMS Message record to the Completed – Sent status (or Open Failed if it doesn’t manage to send any messages)

We send the Guid of the contact the message is being sent to as well as the Guid of the creator of the message to allow as user data to the TextaHQ API – this data is stored with the message and if a reply comes back the data is fed back to us. That allows us to assign the reply back to the original sender and set it regarding the correct contact.

SendSMSActivity.cs

This cool bit of code lets you send SMS messages from workflows! It takes the following parameters

• Recipient number
• Message
• Regarding contact
• User to assign replies to (system user/owner)

Then returns a MessageSent boolean to let you know if it sent or not.

In fact, if you wanted you could actually just register this workflow activity and forget about the SendSMS.cs – but I needed SendSMS.cs to allow me to send a SMS message to a whole course full of students.

(You would just setup a workflow to trigger when statuscode of sms message is set to completed – pending, then send SMS with the appropriate variables, then if it manages to send update the status code to completed – sent or open – failed)

Registering Plug-in assembly

Build the plug-in assemblies and register – this is what the step looks like for me for SendSMS.cs

Conclusion

You should now in theory be able to send SMS messages. I’ve added a ‘Save and Complete’ button to the toolbar for SMS Message activities, and renamed it ‘Send SMS’.

Sorry I don’t have time to tidy this up and write a proper instruction, but there are some other good posts online which I used to help me get this far.

I would have liked to implement party lists to allow sending to multiple contacts, but don’t really need it at this stage.

Hopefully you might find some useful code snippets that you can adapt for use in your project.
One day I might release it all packaged up as a solution!

I’ll post my SMS reply processing ASP.NET form soon to complete the puzzle.