To get started with messaging your customers you need to first add in a topic, the participants related to that topic and templates that your users will interact with to start their conversations off. Using our API suite allows you to have finer control over those topics, templates and conversations.
\nTextKit APIs are built in GraphQL which is a syntax that makes it easier to aggregate data from multiple sources. Instead of needing multiple endpoints, TextKit has a single endpoint that can take care of complex queries and then massage the output to whatever shape you need. For example, you can execute multiple queries in the same call where REST would have required you to make multiple calls to different endpoints. This makes the API and your new application much faster and easier to build.
\nFor a gentle introduction to GraphQL, the official website is an excellent resource:\nhttps://graphql.org/learn/
\nIf you would like to use our GraphQL API you will be assigned an authentication token as well as an API URL upon request.
\nTextKit can integrate with many SSO systems for both representative and administrator login/authentication.
\nPermissions to generate API tokens can be assigned within TextKit to certain administrative users. These tokens can be used to authenticate requests for all APIs that TextKit provides.
\nAuthorization is provided by a role-based access control system, where the token will inherit the role permissions of the user that generates the token, or a subset of those permissions that can be chosen at the time of generation.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"3800659","collectionId":"2508998d-336d-4321-9c1e-e893517124c9","publishedId":"TzzHnZ4W","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"E21D7A"},"publishDate":"2021-08-30T03:33:10.000Z"},"item":[{"name":"Participant","item":[{"name":"Contact","item":[{"name":"FindContactById","event":[{"listen":"test","script":{"id":"3470794b-0e96-458b-b67f-20b8a03e39a8","exec":["pm.test(\"Setting conversation ID\", function () {"," var jsonData = pm.response.json();"," var conversationId = jsonData?.data?.findContactById?.conversations[0]?.conversationId;"," pm.environment.set(\"ConversationId\", conversationId);","});"],"type":"text/javascript"}}],"id":"e0e36bda-5643-42f8-a8f1-7de17a2719ab","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"query FindContact($participantId: ID!) {\n findContactById(id : $participantId) {\n participantId\n firstName\n lastName\n locale\n channels {\n type\n inboundAddress\n outboundAddress\n }\n external {\n externalId\n metadata\n }\n conversations {\n conversationId\n state\n from {\n type\n outboundAddress\n }\n }\n }\n}","variables":"{\n \"participantId\" : \"848a9689-da10-4f49-a2d3-65775339a0e8\"\n}"}},"url":"{{ApiUrl}}/graphql","description":"Queries a Contact by participantId (as a UUID)
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"e0e36bda-5643-42f8-a8f1-7de17a2719ab"},{"name":"SaveContact","event":[{"listen":"test","script":{"id":"dcb00258-8e1f-4cdd-8037-397dcf8cd876","exec":[""],"type":"text/javascript"}}],"id":"0c5e1773-af76-42f8-a388-8ae74807d59a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"mutation SaveContact ($SaveContactInput: SaveContactInput!) {\n saveContact(contact: $SaveContactInput)\n}","variables":"{\n \"SaveContactInput\": {\n \"participantId\": \"848a9689-da10-4f49-a2d3-65775339a0e8\",\n \"firstName\": \"Alice\",\n \"lastName\": \"Aiko\",\n \"locale\": \"en_US\",\n \"channels\": [\n {\n \"type\": \"SMS\",\n \"inboundAddress\": \"+15555555454\",\n \"outboundAddress\": \"+15555555451\"\n }\n ],\n \"external\" : {\n \"externalId\" : \"SF000000001\",\n \"metadata\" : {\n \"city\" : \"Toronto\"\n }\n }\n }\n}"}},"url":"{{ApiUrl}}/graphql","description":"Saves a Contact, this operation creates a new Contact or updates an existing one based on their participantId.
\nAdditionally, for each new Channel; then, a new Conversation is created and the Contact is added as participant in the Conversation.
\nIt returns the provided participantId
\nExternal data that isn't directly maintained by TextKit but is required when integrating with external systems.
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"0c5e1773-af76-42f8-a388-8ae74807d59a"}],"id":"ed3f212f-e388-4174-8936-a5ad0b39ea2b","description":"A contact is a person you would like to have a conversation with, such as a business' customer. These are participants who are going to receive messages from the system.
\n","_postman_id":"ed3f212f-e388-4174-8936-a5ad0b39ea2b"},{"name":"Representative","item":[{"name":"FindRepresentativeById","id":"57d5139b-df05-4dee-afa7-47ec7bc6e7bf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"query FindRepresentative($participantId: ID!) {\n findRepresentativeById(id : $participantId) {\n participantId\n external {\n externalId\n metadata\n }\n authentication {\n identifier\n }\n }\n}","variables":"{\n \"participantId\" : \"d4e44877-ae53-47f1-851b-20c7bfd3b5ec\"\n}"}},"url":"{{ApiUrl}}/graphql","description":"Queries a Representative by participantId.
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"57d5139b-df05-4dee-afa7-47ec7bc6e7bf"},{"name":"SaveRepresentative","event":[{"listen":"test","script":{"id":"ecb65857-1851-4e23-b985-698d47ab9ec4","exec":["pm.test(\"Your test name\", function () {"," var jsonData = pm.response.json();"," console.log(jsonData.data);"," pm.environment.set(\"ParticipantId\", jsonData.data.saveRepresentative);","});"],"type":"text/javascript"}}],"id":"e59ccd5d-dcf8-48d2-87c4-4e001061c3fe","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"mutation SaveRepresentative ($SaveRepresentativeInput: SaveRepresentativeInput!) {\n saveRepresentative(representative: $SaveRepresentativeInput)\n}","variables":"{\n \"SaveRepresentativeInput\": {\n \"participantId\": \"d4e44877-ae53-47f1-851b-20c7bfd3b5ec\",\n \"external\" : {\n \"externalId\" : \"external_U77676\",\n \"metadata\" : {\n \"BRANCH_NAME\" : \"Downtown North\"\n }\n },\n \"authentication\" : {\n \"identifier\" : \"peter@example.com\"\n }\n }\n}"}},"url":"{{ApiUrl}}/graphql","description":"Saves a Representative, this operation creates a new Representative, or updates an existing one based on their participantId.
\nIt returns the provided participantId
\nExternal data that isn't directly maintained by TextKit but is required when integrating with external systems.
\nAssigns a Representative to a Contact. The system is going to make the Representative a Participant in each Conversation belonging to the Contact. This operation also unassigns Representative (if any) previously assigned to all Contacts in the Conversation.
\nIt returns true when successful.
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"aac2b2b9-ac25-4f7e-8396-80d647345cec"},{"name":"UnassignRepresentativeFromContacts","id":"ec777b33-cb29-4a05-bbc2-a307a85c6dc4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"mutation unassignRepresentativeFromContact($UnassignRepresentativeFromContactInput : UnassignRepresentativeFromContactInput!) {\n unassignRepresentativeFromContact(input: $UnassignRepresentativeFromContactInput)\n}","variables":"{\n \"UnassignRepresentativeFromContactInput\" : {\n \"representative\": \"{{RepresentativeParticipantId}}\",\n \"contact\": \"{{ContactParticipantId}}\"\n }\n}"}},"url":"{{ApiUrl}}/graphql","description":"Unassigns a Representative from a Contact. The system is going to remove the Representative as a Participant from each Conversation belonging to the Contact.
\nIt returns true when successful.
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"ec777b33-cb29-4a05-bbc2-a307a85c6dc4"}],"id":"9be48cd0-20c1-4057-9e1c-b6b99d97ed09","description":"A representative is a user within TextKit who will be sending messages to your contacts in conversations.
\n","_postman_id":"9be48cd0-20c1-4057-9e1c-b6b99d97ed09"}],"id":"4f1bb300-a355-4390-a2c1-44f112b29b5d","description":"Participants are those users and contacts involved in a conversation.
\n","_postman_id":"4f1bb300-a355-4390-a2c1-44f112b29b5d"},{"name":"Topic","item":[{"name":"FindTopicById","id":"e3530b27-7cd4-4739-8d29-8c69e5239f54","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"query FindTopic($topicId: ID!) {\n findTopicById(topicId : $topicId) {\n topicId\n name\n description\n state\n external {\n externalId\n metadata\n }\n templates {\n name\n locale\n channel {\n type\n }\n text\n }\n }\n}","variables":"{\n \"topicId\" : \"{{TopicId}}\"\n}"}},"url":"{{ApiUrl}}/graphql","description":"Queries a Topic by topicId.
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"e3530b27-7cd4-4739-8d29-8c69e5239f54"},{"name":"SaveTopic","event":[{"listen":"test","script":{"id":"3fdf2bfc-cabc-47fd-a217-1929749514a1","exec":[""],"type":"text/javascript"}}],"id":"f0b9fa41-5bf3-4d3d-b23a-16f3c54799f5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"mutation SaveTopic ($SaveTopicInput: SaveTopicInput!) {\n saveTopic(input: $SaveTopicInput)\n}","variables":"{\n \"SaveTopicInput\": {\n \"topicId\" : \"{{TopicId}}\",\n \"name\" : \"PayByMobile Campaign\",\n \"description\" : \"Encourage customers to switch to our new app.\",\n \"external\": {\n \"externalId\": \"SFMC00000001\",\n \"metadata\": {\n \"product\": \"PayMyMobile\"\n }\n },\n \"templates\" : [\n {\n \"name\": \"New App Reminder\",\n \"locale\": \"en_CA\",\n \"channel\": {\n \"type\": \"SMS\"\n },\n \"text\": \"Hello {{name}}. I noticed you paid by {{currency}} last time you were in. Did you know we now have a mobile app to make your payments even easier?\"\n }, {\n \"name\": \"Loyalty points\",\n \"locale\": \"en_CA\",\n \"channel\": {\n \"type\": \"SMS\"\n },\n \"text\": \"Hello {{name}}, you are eligible for {{points}} points by using our new mobile app. Would you like to redeem it at your next appointment next week?\"\n }\n ]\n }\n}"}},"url":"{{ApiUrl}}/graphql","description":"Saves a Topic, this operation creates a new Topic, or updates an existing one based on their topicId.
\nIt returns the provided topicId
\nExternal data that isn't directly maintained by TextKit but is required when integrating with external systems.
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"f0b9fa41-5bf3-4d3d-b23a-16f3c54799f5"},{"name":"SaveTopicParticipation","id":"cc035381-8eb9-4f8d-b373-07abdd515e0c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"mutation SaveTopicParticipation ($SaveTopicParticipationInput: SaveTopicParticipationInput!) {\n saveTopicParticipation(input: $SaveTopicParticipationInput)\n}","variables":"{\n \"SaveTopicParticipationInput\": {\n \"topicId\": \"{{TopicId}}\",\n \"participantId\" : \"{{ContactParticipantId}}\",\n \"range\" : {\n \"startsAt\": \"2022-07-17T10:23:53.929335-04:00\",\n \"endsAt\": \"2999-01-01T01:00:00.000Z\"\n },\n \"external\": {\n \"metadata\": {\n \"caslLink\": \"https://casl.link?xxxxxxxx\"\n }\n },\n \"templateVariables\": [\n {\n \"template\": {\n \"name\": \"App Campaign\",\n \"locale\": \"en_CA\",\n \"channel\": {\n \"type\": \"SMS\"\n }\n },\n \"variables\": [\n {\n \"key\": \"name\",\n \"value\": \"Alice A. Abel\"\n }, {\n \"key\": \"currency\",\n \"value\": \"Cash\"\n }\n ]\n }, {\n \"template\": {\n \"name\": \"Loyalty points\",\n \"locale\": \"en_CA\",\n \"channel\": {\n \"type\": \"SMS\"\n }\n },\n \"variables\": [\n {\n \"key\": \"name\",\n \"value\": \"Alice\"\n }, {\n \"key\": \"points\",\n \"value\": \"5000\"\n }\n ]\n }\n ]\n }\n}"}},"url":"{{ApiUrl}}/graphql","description":"Saves a TopicParticipation, this operation creates a new TopicParticipation, or updates an existing one based on their topicId and participantId.
\nA TopicParticipation defines which Participants (i.e: Contacts) participate in a Topic.
\nIt returns true when successful.
\nActivates a Topic to be used for Conversations.
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"c7e1d7a6-e645-429f-aba0-fefe6c2422df"},{"name":"DeactivateTopic","event":[{"listen":"test","script":{"exec":[""],"type":"text/javascript","id":"f605bd38-d317-45af-9006-93ac56a69a09"}}],"id":"53b23cf2-491a-4cd6-a46c-cc5947843f1e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"mutation DeactivateTopic ($topicId: ID!) {\n deactivateTopic(topicId: $topicId)\n}","variables":"{\n \"topicId\" : \"{{TopicId}}\"\n}"}},"url":"{{ApiUrl}}/graphql","description":"Deactivates a Topic and prevents it from being used in Conversatons.
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"53b23cf2-491a-4cd6-a46c-cc5947843f1e"},{"name":"RemoveTopicParticipation","id":"1bf985db-f96e-4e4e-bb1a-65d07c3463ee","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"mutation RemoveTopicParticipation ($RemoveTopicParticipationInput: RemoveTopicParticipationInput!) {\n removeTopicParticipation(input: $RemoveTopicParticipationInput)\n}","variables":"{\n \"RemoveTopicParticipationInput\": {\n \"topicId\": \"{{TopicId}}\",\n \"participantId\" : \"{{ContactParticipantId}}\"\n }\n}"}},"url":"{{ApiUrl}}/graphql","description":"This operation removes a Topic from a Contact.
\nIt returns true when successful.
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"1bf985db-f96e-4e4e-bb1a-65d07c3463ee"}],"id":"9eef27dc-55f6-4954-a1bc-a49674135c6f","description":"Topics are reasons a participant should engage in a conversation. These could be business campaigns.
\n","_postman_id":"9eef27dc-55f6-4954-a1bc-a49674135c6f"},{"name":"Conversation","item":[{"name":"ActivateConversation","event":[{"listen":"test","script":{"exec":[""],"type":"text/javascript","id":"54a99935-0f98-4871-802f-539466010761"}}],"id":"4136d190-7e07-45bc-a139-f5f21b1106ac","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"mutation ActivateConversation ($conversationId: ID!) {\n activateConversation(conversationId: $conversationId)\n}","variables":"{\n \"conversationId\" : \"{{ConversationId}}\"\n}"}},"url":"{{ApiUrl}}/graphql","description":"This triggers the creation of a new conversation ready to go in TextKit. Participants can interact with activated Conversations.
\n","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"4136d190-7e07-45bc-a139-f5f21b1106ac"},{"name":"DeactivateConversation","event":[{"listen":"test","script":{"exec":[""],"type":"text/javascript","id":"9a5edbce-da2b-4b93-90bf-4446aa73c5a2"}}],"id":"9c4e4a9a-c032-48b4-a1e9-331a277954c1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{AuthorizationToken}}","type":"text"}],"body":{"mode":"graphql","graphql":{"query":"mutation deactivateConversation ($conversationId: ID!) {\n deactivateConversation(conversationId: $conversationId)\n}","variables":"{\n \"conversationId\" : \"{{ConversationId}}\"\n}"}},"url":"{{ApiUrl}}/graphql","urlObject":{"path":["graphql"],"host":["{{ApiUrl}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"9c4e4a9a-c032-48b4-a1e9-331a277954c1"}],"id":"025b13c9-7670-4e24-bec5-fd51d87ca54d","description":"Conversations can be interacted with individually. This can be useful for managing individual conversations to perform automatic actions, such as moving them between categories to achieve a certain workflow and improve representative efficiency, or to reassign conversations to a different representative to maintain business continuity or rebalance workloads.
\nConversations can actually be created, managed, and follow their whole lifecycle without ever being included with a topic. This can support workflows that don’t fit within the lifecycle of a topic, especially for conversations that are created in reaction to a contact-initiated event such as an incoming support desk request, or an algorithmic outreach trigger for a particular contact.
\n","_postman_id":"025b13c9-7670-4e24-bec5-fd51d87ca54d"}]}