DID Best Practices

From CDYNE Wiki
Revision as of 09:34, 19 December 2012 by imported>Nfesette (→‎Phone Number Format)
Jump to navigation Jump to search

Send or receive text messages from your website or application with SMS-enabled phone numbers (DIDs): 10-digit phone numbers used for two-way text messaging. Each account license key is assigned one or more DIDs for sending and receiving text messages. CDYNE recommends sending no more than 500 MT messages per DID per day. Add DIDs for higher daily throughput needs, or use short codes for high volume needs.


SimpleSMSSend Method

SimpleSMSSend is recommended for sending single, immediate text messages.

  • When a license key is passed using this method, it will automatically send messages from the DIDs assigned to that license key. For license keys with more than one DID, SMS Notify! API will automatically balance the outgoing messages between assigned DIDs.
  • Additional SMS Notify! API license keys may be generated at no additional cost. Assigning DIDs to each additional license key allows you to pass a designated license key to control which DIDs sends the text message.

AdvancedSMSSend Method

AdvancedSMSSend is recommended for sending scheduled text messages and allows multiple numbers with one message, or multiple numbers with individual messages.

  • You can declare the sending DID in the "AssignedDID" parameter.
  • If a DID is not declared in the “AssignedDID” parameter, the method will automatically send messages from the DIDs assigned to that license key. For license keys with more than one DID, SMS Notify! API will automatically balance the outgoing messages between assigned DIDs.
  • Additional SMS Notify! API license keys may be generated at no additional cost. Assigning DIDs to each additional license key allows you to pass a designated license key to control which DIDs sends the text message.
  • If the DID does not match the license key passed, error code "6" for "InvalidAssignedDID" will return in the SMSError parameter.

Sending to Domestic & International Destinations

Your account DIDs determine which destinations may be reached.

  • U.S. DIDs will send two-way messages to U.S. and Canadian handsets ($1/DID/mo with 1 cent per text message).
  • Canadian DIDs will send two-way messages to U.S. and Canadian handsets ($1/DID/mo with 2 cent outbound/1 cent inbound per text message).
  • International DIDs will send two-way messages within their respective countries (DID and outbound pricing is variable/inbound pricing is 1 cent).
  • U.K. DIDs will send messages to any worldwide destination DIDs are not avaialble in ($1/DID/mo with variable outbound pricing/inbound pricing is 1 cent).

By default, SMS Notify! will send text messages per domestic or international assigned DIDs via round-robin. When you pass a license key with multiple DIDs assigned, SMS Notify! will look for the country code to determine which sending DIDs to use.

When CDYNE detects 1 + area code, we look for a U.S. DID. If a Canadian area code is detected, SMS Notify! will look for a Canadian DID first. If not available, it will look for a U.S. DID to send the text message.

When 011 + country code is detected, SMS Notify! will first look for the local international DID (i.e. sending 011 + 61 will prompt SMS Notify! to use an Australian DID). If not available, it will look for the default U.K. DID for sending.

Step by Step Message Flow

API Request

  1. Your server or application makes a CDYNE SMS Notify! API Request
  2. Message is sent to CDYNE through the API.
  3. Example GET Request: http://wiki.cdyne.com/index.php/SMS_Notify!#Calling_via_REST_.28POST.2FGET.29

API Response

  1. CDYNE replies with an API response
  2. In the Response, any errors immediately noticed are returned in the Response.
  3. Example Response: http://wiki.cdyne.com/index.php/SimpleSMSSend#SimpleSMSSend_Response

Send Message

  1. CDYNE sends message to appropriate aggregator
  2. Message is sent to aggregator
  3. CDYNE sends HTTP POST to your PostBackURL indicating we sent the message to be delivered.
  4. Example Sent PostBack: http://wiki.cdyne.com/index.php/SMS_Message_Sent_Postback

Deliver Message

  1. Aggregator delivers message to appropriate carrier

Handset Delivery

  1. Carrier delivers message to cell phone

PostBackURL System

Know when your SMS was sent or received with the PostBackURL System. CDYNE SMS Notify! API will automatically post information to a URL you specify when text messages are sent or received via DIDs and short codes. PostBackURL data is posted behind the scenes, and is not visible on your webpage. Code samples are provided on how to capture this data to store in a database. CDYNE recommends that the data returned to be stored within your systems for reporting and reference information.

API Throughput

Automated bulk sending or marketing text messages are not allowed with DIDs. Other volume limitations include:

  • Send MT SMS at a rate of 1 message every 2 seconds per DID (This throttle is imposed at server level, anything faster will get auto-queued)
  • Maximum daily volume per DID should be 500 MT messages per day (not limited by CDYNE servers, you will to program this limitation)
  • No restrictions on MO messages

Short codes should be used for projects that require high volume messaging.

Coverage & Area Codes

SMS Notify! will send messages to the U.S., Canada, or worldwide. The turnaround time to obtain account DIDs vary by coverage and whether or not you request an area code specific DID.

SMS to U.S. and Canada: all major U.S. and Canadian carriers are supported.

  • Random U.S. DIDs are available immediately
  • Area code requests take 5 – 7 business days

SMS Worldwide: supports carriers worldwide.

  • Random DIDs are available in 1 – 2 business days

Phone Number Format

USA and Canada

  • 1 + NPA + NXX + XXXX
  • 1 + (Area Code) + Number

Example

  • (1 + 757 + 544 + 9510) = 17575449510

International

  • 0 + 11 + Country Code + Phone number

SMS and Daylight Savings Time

SMS Notify! recognizes the date and time in UTC (Coordinated Universal Time). When clocks move forward 1 hour in the spring, most time zones will need to remove one hour from their UTC offset. For example, Eastern Standard Time (EST) is UTC -5 hours but Eastern Daylight Time (EDT) is UTC -4 hours.