openapi-directory/api/nexmo.com/external-accounts.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.1","servers":[{"url":"https://api.nexmo.com/beta/chatapp-accounts"}],"info":{"contact":{"email":"devrel@vonage.com","name":"Vonage DevRel","url":"https://developer.nexmo.com/"},"description":"The External Accounts API is used to manage accounts for Viber Business Messages, Facebook Messenger and Whatsapp for use in the [Messages](https://developer.nexmo.com/messages/overview) and [Dispatch](https://developer.nexmo.com/dispatch/overview) APIs.","title":"External Accounts API","version":"0.1.5","x-label":"Developer Preview","x-logo":{"url":"https://www.vonage.com/content/dam/vonage/us-en/api/illustrations/Mobile_APIs_Services.svg"},"x-origin":[{"format":"openapi","url":"https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/external-accounts.yml","version":"3.0"}],"x-providerName":"nexmo.com","x-serviceName":"external-accounts"},"tags":[{"description":"Inbound messages to an external account which is linked to an application will be delivered to the application's inbound URL.","name":"Application"},{"description":"An external-account used as the `from` field in the Messages API and Dispatch API","name":"Account"},{"description":"Managing your [Facebook Messenger](https://developer.nexmo.com/messages/concepts/facebook) account","name":"Facebook Messenger"},{"description":"Managing your [Viber Service Message](https://developer.nexmo.com/messages/concepts/viber) account","name":"Viber Service Message"},{"description":"Managing your [Whatsapp](https://developer.nexmo.com/messages/concepts/whatsapp) account","name":"Whatsapp"}],"paths":{"/":{"get":{"operationId":"GetAllAccounts","parameters":[{"description":"Filter by provider","in":"query","name":"provider","required":false,"schema":{"enum":["messenger","viber_service_msg","whatsapp"],"type":"string"}},{"description":"Page number of the results","in":"query","name":"page_number","required":false,"schema":{"default":1,"example":1,"type":"integer"}},{"description":"Page size of the results","in":"query","name":"page_size","required":false,"schema":{"default":20,"example":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"_embedded":{"items":{"$ref":"#/components/schemas/GetAllAccountResponse"},"type":"array"},"_links":{"properties":{"first":{"properties":{"href":{"example":"https://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10","type":"string"}},"type":"object"},"last":{"properties":{"href":{"example":"https://api.nexmo.com/beta/chatapp-accounts?page_number=4&page_size=10","type":"string"}},"type":"object"},"next":{"properties":{"href":{"example":"https://api.nexmo.com/beta/chatapp-accounts?page_number=3&page_size=10","type":"string"}},"type":"object"},"prev":{"properties":{"href":{"example":"https://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10","type":"string"}},"type":"object"},"self":{"properties":{"href":{"example":"https://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10","type":"string"}},"type":"object"}},"type":"object"},"page_number":{"example":1,"type":"integer"},"page_size":{"example":10,"type":"integer"}},"type":"object"}}},"description":"OK."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Response"}}},"description":"Unauthorized."}},"security":[{"bearerAuth":[]},{"basicAuth":[]}],"summary":"Retrieve all accounts you own","tags":["Account"]}},"/messenger":{"post":{"operationId":"CreateMessengerAccount","requestBody":{"content":{"application/json":{"schema":{"properties":{"access_token":{"description":"This is the Facebook Business Page token. You can obtain the token using one of the following methods:\n\n* Linking your Facebook Business Page to your account [with our Dashboard tool](https://dashboard.nexmo.com/messages/social-channels/facebook-connect)\n* Requesting a Page Access Token using the steps in the [Facebook token reference](https://developers.facebook.com/docs/pages/access-tokens/)\n","example":"myAccessToken","type":"string"},"applications":{"description":"Contains a list of application IDs which are linked to the account. <ul> <li>There is just one application allowed per an account.</li> <li>The application type must be type \"messages\".</li> </ul> For more information see [Application API spec](https://developer.nexmo.com/api/application.v2)","example":["optionalApplicationId"],"items":{"type":"string"},"maxItems":1,"minItems":0,"type":"array"},"external_id":{"description":"This is the unique identifier within the provider's domain. In this case it is the Page ID for your Facebook Page. Go to your Facebook Page, click \"Settings\", click \"Messenger platform \" scroll down to \"Messenger link\" to find your Page ID.","example":"12345678","type":"string"},"name":{"description":"Custom account name","example":"optionalName","type":"string"}},"required":["external_id","access_token"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessengerAccountResponse"}}},"description":"Created."},"400":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Found errors validating 1 of your submitted parameters.","type":"string"},"instance":{"example":null,"type":"string"},"invalid_params":{"items":{"properties":{"name":{"example":"external_id","type":"string"},"reason":{"example":"Missing `external_id` field","type":"string"}},"type":"object"},"type":"array"},"title":{"example":"Your request parameters didn't validate.","type":"string"},"type":{"example":"https://www.nexmo.com/messages/Errors#InvalidParams","type":"string"}},"type":"object"}}},"description":"Bad Request."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Response"}}},"description":"Unauthorized."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/403Response"}}},"description":"Forbidden."}},"security":[{"bearerAuth":[]},{"basicAuth":[]}],"summary":"Create a Messenger account","tags":["Facebook Messenger"]}},"/messenger/{external_id}":{"delete":{"operationId":"DeleteMessengerAccount","parameters":[{"description":"External id of the account you want to delete. In this case it is the Facebook Page ID.","in":"path","name":"external_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Response"}}},"description":"Unauthorized."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/403Response"}}},"description":"Forbidden."},"404":{"description":"Not Found."}},"security":[{"bearerAuth":[]},{"basicAuth":[]}],"summary":"Delete a Messenger account","tags":["Facebook Messenger"]},"get":{"operationId":"GetMessengerAccount","parameters":[{"description":"External id of the account you want to retrieve. In this case it is the Facebook Page ID.","in":"path","name":"external_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessengerAccountResponse"}}},"description":"OK."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Response"}}},"description":"Unauthorized."},"404":{"description":"Not Found."}},"security":[{"bearerAuth":[]},{"basicAuth":[]}],"summary":"Retrieve a Messenger account","tags":["Facebook Messenger"]},"patch":{"operationId":"UpdateMessengerAccount","parameters":[{"description":"External id of the account you want to update. In this case it is the Facebook Page ID.","in":"path","name":"external_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"access_token":{"example":"updatedAccessToken","type":"string"},"applications":{"example":["newApplicationId"],"items":{"type":"string"},"type":"array"},"name":{"description":"The new account name","example":"newName","type":"string"}},"type":"object"}}},"description":"Request body can contain any of the following","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"access_token":{"description":"The provider access token","example":"updatedAccessToken","type":"string"},"api_key":{"description":"The external api key for this account","example":"abcd1234","type":"string"},"applications":{"description":"The array of associated application ids","example":["newApplicationId"],"items":{"type":"string"},"type":"array"},"external_id":{"description":"The external identifier for this account. In this case it is the Facebook Page ID.","example":"12345678","type":"string"},"name":{"description":"The account name","example":"newName","type":"string"},"provider":{"description":"The provider (will be `messenger`).","example":"messenger","type":"string"}},"required":["external_id","api_key","provider","access_token"],"type":"object"}}},"description":"OK."},"400":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Found errors validating 1 of your submitted parameters.","type":"string"},"instance":{"example":null,"type":"string"},"invalid_params":{"items":{"properties":{"name":{"example":"external_id","type":"string"},"reason":{"example":"'external_id' parameter cannot be changed","type":"string"}},"type":"object"},"type":"array"},"title":{"example":"Your request parameters didn't validate.","type":"string"},"type":{"example":"https://www.nexmo.com/messages/Errors#InvalidParams","type":"string"}},"type":"object"}}},"description":"Bad Request."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Response"}}},"description":"Unauthorized."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/403Response"}}},"description":"Forbidden."},"404":{"description":"Not Found."}},"security":[{"bearerAuth":[]},{"basicAuth":[]}],"summary":"Update a Messenger account","tags":["Facebook Messenger"]}},"/viber_service_msg/{external_id}":{"get":{"operationId":"GetVSMAccount","parameters":[{"description":"External id of the account you want to retrieve. In this case it will be your Viber Service Message ID.","in":"path","name":"external_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VSMAccountResponse"}}},"description":"OK."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Response"}}},"description":"Unauthorized."},"404":{"description":"Not Found."}},"security":[{"bearerAuth":[]},{"basicAuth":[]}],"summary":"Retrieve a Viber Service Message account","tags":["Viber Service Message"]}},"/whatsapp/{external_id}":{"get":{"operationId":"GetWAAccount","parameters":[{"description":"External id of the account you want to retrieve. In this case it will be the WhatsApp number.","in":"path","name":"external_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WAAccountResponse"}}},"description":"OK."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Response"}}},"description":"Unauthorized."},"404":{"description":"Not Found."}},"security":[{"bearerAuth":[]},{"basicAuth":[]}],"summary":"Retrieve a Whatsapp account","tags":["WhatsApp"]}},"/{provider}/{external_id}/applications":{"post":{"operationId":"LinkApplication","parameters":[{"description":"Provider of the account you want to assign an application to","in":"path","name":"provider","required":true,"schema":{"enum":["messenger","viber_service_msg","whatsapp"],"type":"string"}},{"description":"External id of the account you want to assign an application to. This is channel dependent. For Facebook it will be your Facebook Page ID, for Viber your Viber Service Message ID and for WhatsApp your WhatsApp number.","in":"path","name":"external_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"application":{"description":"There is just one application allowed per an account. The application type must be type \"messages\". For more information please see [Application API Spec](https://developer.nexmo.com/api/application.v2)","example":"applicationId","type":"string"}},"required":["application"],"type":"object"}}},"description":"Request body can contain any of the following. Please note, the only one application can be linked to the account.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResponse"}}},"description":"OK."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Response"}}},"description":"Unauthorized."},"403":{"content":{"application/json":{"schema":{"properties":{"detail":{"description":"The application does not exist or the application type is not \"messages\"","example":"Cannot link application","type":"string"},"title":{"example":"Forbidden","type":"string"},"type":{"example":"https://www.nexmo.com/messages/Errors#Forbidden","type":"string"}},"type":"object"}}},"description":"Forbidden."},"409":{"content":{"application/json":{"schema":{"properties":{"detail":{"description":"The account reached limit of maximum number of linked applications. (The only one application is allowed per an account)","example":"Unable to link application","type":"string"},"title":{"example":"Application conflict","type":"string"},"type":{"example":"https://www.nexmo.com/messages/Errors#Conflict","type":"string"}},"type":"object"}}},"description":"Conflict."}},"security":[{"bearerAuth":[]},{"basicAuth":[]}],"summary":"Link application to an account","tags":["Application"]}},"/{provider}/{external_id}/applications/{application_id}":{"delete":{"operationId":"UnliWithoutApplicationnkApplication","parameters":[{"description":"Provider of the account you want to unlink an application from","in":"path","name":"provider","required":true,"schema":{"enum":["messenger","viber_service_msg","whatsapp"],"type":"string"}},{"description":"External id of the account you want to unlink an application from","in":"path","name":"external_id","required":true,"schema":{"type":"string"}},{"description":"Id of the application you want to unlink","in":"path","name":"application_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Response"}}},"description":"Unauthorized."},"403":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Cannot unlink application","type":"string"},"title":{"example":"Forbidden","type":"string"},"type":{"example":"https://www.nexmo.com/messages/Errors#Forbidden","type":"string"}},"type":"object"}}},"description":"Forbidden."},"409":{"content":{"application/json":{"schema":{"properties":{"detail":{"description":"The application is not linked or doesn't exist.","example":"Unable to unlink application","type":"string"},"title":{"example":"Application conflict","type":"string"},"type":{"example":"https://www.nexmo.com/messages/Errors#Conflict","type":"string"}},"type":"object"}}},"description":"Conflict."}},"security":[{"bearerAuth":[]},{"basicAuth":[]}],"summary":"Unlink application from an account","tags":["Application"]}}},"components":{"schemas":{"401Response":{"properties":{"detail":{"example":"Request header 'Authorization' missing / Invalid Token","type":"string"},"title":{"example":"Unauthorised","type":"string"}},"type":"object"},"403Response":{"properties":{"title":{"example":"Wrong authentication - You are not authorised to access this resource","type":"string"}},"type":"object"},"AccountResponse":{"properties":{"access_token":{"description":"The provider access token (only for `messenger`)","example":"accessToken","type":"string"},"api_key":{"description":"The external api key for this account","example":"abcd1234","type":"string"},"applications":{"description":"The array of associated application ids","example":["applicationId"],"items":{"type":"string"},"type":"array"},"external_id":{"description":"The external identifier for this account","example":"12345678","type":"string"},"name":{"description":"The account name","example":"name","type":"string"},"provider":{"description":"The provider (will be one of `messenger, viber_service_msg, whatsapp`).","enum":["messenger","viber_service_msg","whatsapp"],"example":"messenger","type":"string"}},"required":["external_id","api_key","provider"],"type":"object"},"GetAllAccountResponse":{"allOf":[{"$ref":"#/components/schemas/MessengerAccountResponse"},{"$ref":"#/components/schemas/VSMAccountResponse"},{"$ref":"#/components/schemas/WAAccountResponse"}]},"MessengerAccountResponse":{"properties":{"access_token":{"description":"The provider access token","example":"myAccessToken","type":"string"},"api_key":{"description":"The external api key for this account","example":"abcd1234","type":"string"},"applications":{"description":"The array of associated application ids","example":["optionalApplicationId"],"items":{"type":"string"},"type":"array"},"external_id":{"description":"The external identifier for this account","example":"12345678","type":"string"},"name":{"description":"The account name","example":"optionalName","type":"string"},"provider":{"description":"The provider (will be `messenger`).","example":"messenger","type":"string"}},"required":["external_id","api_key","provider","access_token"],"type":"object"},"VSMAccountResponse":{"properties":{"api_key":{"description":"The external api key for this account","example":"abcd1234","type":"string"},"applications":{"description":"The array of associated application ids","example":["optionalApplicationId"],"items":{"type":"string"},"type":"array"},"external_id":{"description":"The external identifier for this account","example":"12345678","type":"string"},"name":{"description":"The account name","example":"optionalName","type":"string"},"provider":{"description":"The provider (will be `viber_service_msg`).","example":"viber_service_msg","type":"string"}},"required":["external_id","api_key","provider"],"type":"object"},"WAAccountResponse":{"properties":{"api_key":{"description":"The external api key for this account","example":"abcd1234","type":"string"},"applications":{"description":"The array of associated application ids","example":["optionalApplicationId"],"items":{"type":"string"},"type":"array"},"external_id":{"description":"The external identifier for this account","example":"12345678","type":"string"},"name":{"description":"The account name","example":"optionalName","type":"string"},"provider":{"description":"The provider (will be `whatsapp`).","example":"whatsapp","type":"string"}},"required":["external_id","api_key","provider"],"type":"object"}},"securitySchemes":{"basicAuth":{"scheme":"basic","type":"http"},"bearerAuth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"}}}}