How to Send a Message

Within Text In Church, messages are sent sent to contacts--either a single person or a group of people. In order to send a message, the contact_id or group_id will need to be obtained first. If a contact doesn't exist, then one will need to be created.

When the system sends out a message, it goes through a series of steps and checks. This process is rather complex but what is important is that a receipt is created for each recipient of the message. Once this has completed, the system will send out each receipt. The receipt represents a log of what happened with that message and recipient.

STEP 1: Find the contact or group

To search for a contact, the contact.php endpoint may be used. The contact can be searched by using primary_phone, contact_email, or search. Search will look for a matching name, phone number, or email address.

curl --request GET \
     --url https://api.textinchurch.com/API/1_0/contact.php?primary_phone=5556667777 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<api_key>>'

RESPONSE:

[
    {
        "contact_id": "7082040",
        "hash": "YMKiGjtmhEvCoBAXkwNZ",
        "contact_first_name": "Ben",
        "contact_last_name": "Solo",
		    ...
    }
]

To search for a group, the group.php endpoint may be used. The group can be found by passing the group_name.

curl --request GET \
     --url https://api.textinchurch.com/API/1_0/group.php?group_name=Example \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<api_key>>'

[
    {
        "group_id": "203985",
        "hash": "RdXt4fleaLTW3XknoJkn",
        "group_name": "Example Group for Sending Messages",
		    ...
    }
]

STEP 2: Create the message

Messages can be created by making a POST to the message.php endpoint.

SENDING A TEXT MESSAGE

Property	Description
contact_id --or-- group_id	(REQUIRED) The numerical identifier of the person or group to whom the message will be sent. If the contact record does not have a valid primary_phone, the message will fail and this will be documented in the receipt.
msg_type	(REQUIRED) The type of message. For text messages, this should be "sms".
msg_content	(REQUIRED)The text of the message that the recipient sees. The message may contain variables encapsulated in brackets. For example, {FIRST_NAME}.
msg_send_time	The date as to when the message will be delivered. Omit to send the message now.
connection_id	The numerical identifier for the phone number to use when sending the text message. If omitted, the system will default to the primary phone number on the account.

curl --request POST \
     --url https://api.textinchurch.com/API/1_0/message.php \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<api_key>>' \
	   --data contact_id="7082040" \
	   --data msg_type="sms" \
	   --data-urlencode msg_content="Thank you for joining us for worship!"

SENDING AN EMAIL

Property	Description
contact_id --or-- group_id	(REQUIRED) The numerical identifier of the person or group to whom the message will be sent. If the contact record does not have a valid primary_phone, the message will fail and this will be documented in the receipt.
msg_type	(REQUIRED) The type of message. For text messages, this should be "email".
msg_from_email	(REQUIRED) The email address to which this email will appear to be from. The system will not use this email address to send the message (to avoid spoofing) but will set this as the reply-to.
msg_from_name	(REQUIRED) The name of the person from whom the email is coming.
msg_subject	(REQUIRED) The subject of the email being sent. The subject may contain variables.
msg_content	(REQUIRED)The text or HTML of the email that the recipient sees. The message may contain variables encapsulated in brackets. For example, {FIRST_NAME}.
msg_send_time	The date as to when the email will be delivered. Omit to send the emailnow.

curl --request POST \
     --url https://api.textinchurch.com/API/1_0/message.php \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<api_key>>' \
	   --data contact_id="7082040" \
	   --data msg_type="email" \
	   --data msg_from_email="[email protected]" \
	   --data msg_from_name="Pastor Luke" \
	   --data msg_subject="Thank you for joining us for worship!" \
	   --data-urlencode msg_content="We are so happy you were able to join us."